# User Manual

## Introduction

rocSPARSE is a library that contains basic linear algebra subroutines for sparse matrices and vectors written in HiP for GPU devices. It is designed to be used from C and C++ code. The functionality of rocSPARSE is organized in the following categories:

- Sparse Auxiliary Functions describe available helper functions that are required for subsequent library calls.

- Sparse Level 1 Functions describe operations between a vector in sparse format and a vector in dense format.

- Sparse Level 2 Functions describe operations between a matrix in sparse format and a vector in dense format.

- Sparse Level 3 Functions describe operations between a matrix in sparse format and multiple vectors in dense format.

- Sparse Extra Functions describe operations that manipulate sparse matrices.

- Preconditioner Functions describe manipulations on a matrix in sparse format to obtain a preconditioner.

- Sparse Conversion Functions describe operations on a matrix in sparse format to obtain a different matrix format.

- Reordering Functions describe operations on a matrix in sparse format to obtain a reordering.

The code is open and hosted here: https://github.com/ROCmSoftwarePlatform/rocSPARSE

## Building and Installing

### Prerequisites

rocSPARSE requires a ROCm enabled platform, more information here.

### Installing pre-built packages

rocSPARSE can be installed from AMD ROCm repository. For detailed instructions on how to set up ROCm on different platforms, see the AMD ROCm Platform Installation Guide for Linux.

rocSPARSE can be installed on e.g. Ubuntu using

    $ sudo apt-get update
    $ sudo apt-get install rocsparse

Once installed, rocSPARSE can be used just like any other library with a C API. The header file will need to be included in the user code in order to make calls into rocSPARSE, and the rocSPARSE shared library will become link-time and run-time dependent for the user application.

### Building rocSPARSE from source

Building from source is not necessary, as rocSPARSE can be used after installing the pre-built packages as described above. If desired, the following instructions can be used to build rocSPARSE from source. Furthermore, the following compile-time dependencies must be met

- git

- CMake 3.5 or later

- AMD ROCm

- rocPRIM

- googletest (optional, for clients)

#### Download rocSPARSE

The rocSPARSE source code is available at the rocSPARSE GitHub page. Download the master branch using:

    $ git clone -b master https://github.com/ROCmSoftwarePlatform/rocSPARSE.git
    $ cd rocSPARSE

Below are steps to build different packages of the library, including dependencies and clients. It is recommended to install rocSPARSE using the install.sh script.

#### Using install.sh to build rocSPARSE with dependencies

The following table lists common uses of install.sh to build dependencies + library.

Command | Description
--- | ---
./install.sh -h | Print help information.
./install.sh -d | Build dependencies and library in your local directory. The -d flag only needs to be used once. For subsequent invocations of install.sh it is not necessary to rebuild the dependencies.
./install.sh | Build library in your local directory. It is assumed dependencies are available.
./install.sh -i | Build library, then build and install rocSPARSE package in /opt/rocm/rocsparse. You will be prompted for sudo access. This will install for all users.

#### Using install.sh to build rocSPARSE with dependencies and clients

The client contains example code, unit tests and benchmarks. Common uses of install.sh to build them are listed in the table below.

Command | Description
--- | ---
./install.sh -h | Print help information.
./install.sh -dc | Build dependencies, library and client in your local directory. The -d flag only needs to be used once. For subsequent invocations of install.sh it is not necessary to rebuild the dependencies.
./install.sh -c | Build library and client in your local directory. It is assumed dependencies are available.
./install.sh -idc | Build library, dependencies and client, then build and install rocSPARSE package in /opt/rocm/rocsparse. You will be prompted for sudo access. This will install for all users.
./install.sh -ic | Build library and client, then build and install rocSPARSE package in opt/rocm/rocsparse. You will be prompted for sudo access. This will install for all users.

#### Using individual commands to build rocSPARSE

CMake 3.5 or later is required in order to build rocSPARSE. The rocSPARSE library contains both, host and device code, therefore the HIP compiler must be specified during cmake configuration process.

rocSPARSE can be built using the following commands:

    # Create and change to build directory
    $ mkdir -p build/release ; cd build/release

    # Default install path is /opt/rocm, use -DCMAKE_INSTALL_PREFIX=<path> to adjust it
    $ CXX=/opt/rocm/bin/hipcc cmake ../..

    # Compile rocSPARSE library
    $ make -j$(nproc)

    # Install rocSPARSE to /opt/rocm
    $ make install

GoogleTest is required in order to build rocSPARSE clients.

rocSPARSE with dependencies and clients can be built using the following commands:

    # Install googletest
    $ mkdir -p build/release/deps ; cd build/release/deps
    $ cmake ../../../deps
    $ make -j$(nproc) install

    # Change to build directory
    $ cd ..

    # Default install path is /opt/rocm, use -DCMAKE_INSTALL_PREFIX=<path> to adjust it
    $ CXX=/opt/rocm/bin/hipcc cmake ../.. -DBUILD_CLIENTS_TESTS=ON \
                                          -DBUILD_CLIENTS_BENCHMARKS=ON \
                                          -DBUILD_CLIENTS_SAMPLES=ON

    # Compile rocSPARSE library
    $ make -j$(nproc)

    # Install rocSPARSE to /opt/rocm
    $ make install

#### Common build problems

1. Issue: Could not find a package configuration file provided by “ROCM” with any of the following names: ROCMConfig.cmake, rocm-config.cmake

   Solution: Install ROCm cmake modules

#### Simple Test

You can test the installation by running one of the rocSPARSE examples, after successfully compiling the library with clients.

    # Navigate to clients binary directory
    $ cd rocSPARSE/build/release/clients/staging

    # Execute rocSPARSE example
    $ ./example_csrmv 1000

### Supported Targets

Currently, rocSPARSE is supported under the following operating systems

- Ubuntu 16.04

- Ubuntu 18.04

- CentOS 7

- SLES 15

To compile and run rocSPARSE, AMD ROCm Platform is required.

The following HIP capable devices are currently supported

- gfx803 (e.g. Fiji)

- gfx900 (e.g. Vega10, MI25)

- gfx906 (e.g. Vega20, MI50, MI60)

- gfx908

## Device and Stream Management

`hipSetDevice()` and `hipGetDevice()` are HIP device management APIs. They are NOT part of the rocSPARSE API.

### Asynchronous Execution

All rocSPARSE library functions, unless otherwise stated, are non blocking and executed asynchronously with respect to the host. They may return before the actual computation has finished. To force synchronization, `hipDeviceSynchronize()` or `hipStreamSynchronize()` can be used. This will ensure that all previously executed rocSPARSE functions on the device / this particular stream have completed.

### HIP Device Management

Before a HIP kernel invocation, users need to call `hipSetDevice()` to set a device, e.g. device 1. If users do not explicitly call it, the system by default sets it as device 0. Unless users explicitly call `hipSetDevice()` to set to another device, their HIP kernels are always launched on device 0.

The above is a HIP (and CUDA) device management approach and has nothing to do with rocSPARSE. rocSPARSE honors the approach above and assumes users have already set the device before a rocSPARSE routine call.

Once users set the device, they create a handle with rocsparse_create_handle().

Subsequent rocSPARSE routines take this handle as an input parameter. rocSPARSE ONLY queries (by `hipGetDevice()`) the user’s device; rocSPARSE does NOT set the device for users. If rocSPARSE does not see a valid device, it returns an error message. It is the users’ responsibility to provide a valid device to rocSPARSE and ensure the device safety.

Users CANNOT switch devices between rocsparse_create_handle() and rocsparse_destroy_handle(). If users want to change device, they must destroy the current handle and create another rocSPARSE handle.

### HIP Stream Management

HIP kernels are always launched in a queue (also known as stream).

If users do not explicitly specify a stream, the system provides a default stream, maintained by the system. Users cannot create or destroy the default stream. However, users can freely create new streams (with `hipStreamCreate()`) and bind it to the rocSPARSE handle using rocsparse_set_stream(). HIP kernels are invoked in rocSPARSE routines. The rocSPARSE handle is always associated with a stream, and rocSPARSE passes its stream to the kernels inside the routine. One rocSPARSE routine only takes one stream in a single invocation. If users create a stream, they are responsible for destroying it.

### Multiple Streams and Multiple Devices

If the system under test has multiple HIP devices, users can run multiple rocSPARSE handles concurrently, but can NOT run a single rocSPARSE handle on different discrete devices. Each handle is associated with a particular singular device, and a new handle should be created for each additional device.

## Storage Formats

### COO storage format

The Coordinate (COO) storage format represents a \(m \times n\) matrix by

m | number of rows (integer).
n | number of columns (integer).
nnz | number of non-zero elements (integer).
coo_val | array of `nnz` elements containing the data (floating point).
coo_row_ind | array of `nnz` elements containing the row indices (integer).
coo_col_ind | array of `nnz` elements containing the column indices (integer).

The COO matrix is expected to be sorted by row indices and column indices per row. Furthermore, each pair of indices should appear only once. Consider the following \(3 \times 5\) matrix and the corresponding COO structures, with \(m = 3, n = 5\) and \(\text{nnz} = 8\) using zero based indexing:

\[\begin{split}A = \begin{pmatrix} 1.0 & 2.0 & 0.0 & 3.0 & 0.0 \\ 0.0 & 4.0 & 5.0 & 0.0 & 0.0 \\ 6.0 & 0.0 & 0.0 & 7.0 & 8.0 \\ \end{pmatrix}\end{split}\]

where

\[\begin{split}\begin{array}{ll} \text{coo_val}[8] & = \{1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0\} \\ \text{coo_row_ind}[8] & = \{0, 0, 0, 1, 1, 2, 2, 2\} \\ \text{coo_col_ind}[8] & = \{0, 1, 3, 1, 2, 0, 3, 4\} \end{array}\end{split}\]

### COO (AoS) storage format

The Coordinate (COO) Array of Structure (AoS) storage format represents a \(m \times n\) matrix by

m | number of rows (integer).
n | number of columns (integer).
nnz | number of non-zero elements (integer).
coo_val | array of `nnz` elements containing the data (floating point).
coo_ind | array of `2 * nnz` elements containing alternating row and column indices (integer).

The COO (AoS) matrix is expected to be sorted by row indices and column indices per row. Furthermore, each pair of indices should appear only once. Consider the following \(3 \times 5\) matrix and the corresponding COO (AoS) structures, with \(m = 3, n = 5\) and \(\text{nnz} = 8\) using zero based indexing:

\[\begin{split}A = \begin{pmatrix} 1.0 & 2.0 & 0.0 & 3.0 & 0.0 \\ 0.0 & 4.0 & 5.0 & 0.0 & 0.0 \\ 6.0 & 0.0 & 0.0 & 7.0 & 8.0 \\ \end{pmatrix}\end{split}\]

where

\[\begin{split}\begin{array}{ll} \text{coo_val}[8] & = \{1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0\} \\ \text{coo_ind}[16] & = \{0, 0, 0, 1, 0, 3, 1, 1, 1, 2, 2, 0, 2, 3, 2, 4\} \\ \end{array}\end{split}\]

### CSR storage format

The Compressed Sparse Row (CSR) storage format represents a \(m \times n\) matrix by

m | number of rows (integer).
n | number of columns (integer).
nnz | number of non-zero elements (integer).
csr_val | array of `nnz` elements containing the data (floating point).
csr_row_ptr | array of `m+1` elements that point to the start of every row (integer).
csr_col_ind | array of `nnz` elements containing the column indices (integer).

The CSR matrix is expected to be sorted by column indices within each row. Furthermore, each pair of indices should appear only once. Consider the following \(3 \times 5\) matrix and the corresponding CSR structures, with \(m = 3, n = 5\) and \(\text{nnz} = 8\) using one based indexing:

\[\begin{split}A = \begin{pmatrix} 1.0 & 2.0 & 0.0 & 3.0 & 0.0 \\ 0.0 & 4.0 & 5.0 & 0.0 & 0.0 \\ 6.0 & 0.0 & 0.0 & 7.0 & 8.0 \\ \end{pmatrix}\end{split}\]

where

\[\begin{split}\begin{array}{ll} \text{csr_val}[8] & = \{1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0\} \\ \text{csr_row_ptr}[4] & = \{1, 4, 6, 9\} \\ \text{csr_col_ind}[8] & = \{1, 2, 4, 2, 3, 1, 4, 5\} \end{array}\end{split}\]

### CSC storage format

The Compressed Sparse Column (CSC) storage format represents a \(m \times n\) matrix by

m | number of rows (integer).
n | number of columns (integer).
nnz | number of non-zero elements (integer).
csc_val | array of `nnz` elements containing the data (floating point).
csc_col_ptr | array of `n+1` elements that point to the start of every column (integer).
csc_row_ind | array of `nnz` elements containing the row indices (integer).

The CSC matrix is expected to be sorted by row indices within each column. Furthermore, each pair of indices should appear only once. Consider the following \(3 \times 5\) matrix and the corresponding CSC structures, with \(m = 3, n = 5\) and \(\text{nnz} = 8\) using one based indexing:

\[\begin{split}A = \begin{pmatrix} 1.0 & 2.0 & 0.0 & 3.0 & 0.0 \\ 0.0 & 4.0 & 5.0 & 0.0 & 0.0 \\ 6.0 & 0.0 & 0.0 & 7.0 & 8.0 \\ \end{pmatrix}\end{split}\]

where

\[\begin{split}\begin{array}{ll} \text{csc_val}[8] & = \{1.0, 6.0, 2.0, 4.0, 5.0, 3.0, 7.0, 8.0\} \\ \text{csc_col_ptr}[6] & = \{1, 3, 5, 6, 8, 9\} \\ \text{csc_row_ind}[8] & = \{1, 3, 1, 2, 2, 1, 3, 3\} \end{array}\end{split}\]

### BSR storage format

The Block Compressed Sparse Row (BSR) storage format represents a \((mb \cdot \text{bsr_dim}) \times (nb \cdot \text{bsr_dim})\) matrix by

mb | number of block rows (integer)
nb | number of block columns (integer)
nnzb | number of non-zero blocks (integer)
bsr_val | array of `nnzb * bsr_dim * bsr_dim` elements containing the data (floating point). Blocks can be stored column-major or row-major.
bsr_row_ptr | array of `mb+1` elements that point to the start of every block row (integer).
bsr_col_ind | array of `nnzb` elements containing the block column indices (integer).
bsr_dim | dimension of each block (integer).

The BSR matrix is expected to be sorted by column indices within each row. If \(m\) or \(n\) are not evenly divisible by the block dimension, then zeros are padded to the matrix, such that \(mb = (m + \text{bsr_dim} - 1) / \text{bsr_dim}\) and \(nb = (n + \text{bsr_dim} - 1) / \text{bsr_dim}\). Consider the following \(4 \times 3\) matrix and the corresponding BSR structures, with \(\text{bsr_dim} = 2, mb = 2, nb = 2\) and \(\text{nnzb} = 4\) using zero based indexing and column-major storage:

\[\begin{split}A = \begin{pmatrix} 1.0 & 0.0 & 2.0 \\ 3.0 & 0.0 & 4.0 \\ 5.0 & 6.0 & 0.0 \\ 7.0 & 0.0 & 8.0 \\ \end{pmatrix}\end{split}\]

with the blocks \(A_{ij}\)

\[\begin{split}A_{00} = \begin{pmatrix} 1.0 & 0.0 \\ 3.0 & 0.0 \\ \end{pmatrix}, A_{01} = \begin{pmatrix} 2.0 & 0.0 \\ 4.0 & 0.0 \\ \end{pmatrix}, A_{10} = \begin{pmatrix} 5.0 & 6.0 \\ 7.0 & 0.0 \\ \end{pmatrix}, A_{11} = \begin{pmatrix} 0.0 & 0.0 \\ 8.0 & 0.0 \\ \end{pmatrix}\end{split}\]

such that

\[\begin{split}A = \begin{pmatrix} A_{00} & A_{01} \\ A_{10} & A_{11} \\ \end{pmatrix}\end{split}\]

with arrays representation

\[\begin{split}\begin{array}{ll} \text{bsr_val}[16] & = \{1.0, 3.0, 0.0, 0.0, 2.0, 4.0, 0.0, 0.0, 5.0, 7.0, 6.0, 0.0, 0.0, 8.0, 0.0, 0.0\} \\ \text{bsr_row_ptr}[3] & = \{0, 2, 4\} \\ \text{bsr_col_ind}[4] & = \{0, 1, 0, 1\} \end{array}\end{split}\]

### GEBSR storage format

The General Block Compressed Sparse Row (GEBSR) storage format represents a \((mb \cdot \text{bsr_row_dim}) \times (nb \cdot \text{bsr_col_dim})\) matrix by

mb | number of block rows (integer)
nb | number of block columns (integer)
nnzb | number of non-zero blocks (integer)
bsr_val | array of `nnzb * bsr_row_dim * bsr_col_dim` elements containing the data (floating point). Blocks can be stored column-major or row-major.
bsr_row_ptr | array of `mb+1` elements that point to the start of every block row (integer).
bsr_col_ind | array of `nnzb` elements containing the block column indices (integer).
bsr_row_dim | row dimension of each block (integer).
bsr_col_dim | column dimension of each block (integer).

The GEBSR matrix is expected to be sorted by column indices within each row. If \(m\) is not evenly divisible by the row block dimension or \(n\) is not evenly divisible by the column block dimension, then zeros are padded to the matrix, such that \(mb = (m + \text{bsr_row_dim} - 1) / \text{bsr_row_dim}\) and \(nb = (n + \text{bsr_col_dim} - 1) / \text{bsr_col_dim}\). Consider the following \(4 \times 5\) matrix and the corresponding GEBSR structures, with \(\text{bsr_row_dim} = 2\), \(\text{bsr_col_dim} = 3\), mb = 2, nb = 2` and \(\text{nnzb} = 4\) using zero based indexing and column-major storage:

\[\begin{split}A = \begin{pmatrix} 1.0 & 0.0 & 0.0 & 2.0 & 0.0 \\ 3.0 & 0.0 & 4.0 & 0.0 & 0.0 \\ 5.0 & 6.0 & 0.0 & 7.0 & 0.0 \\ 0.0 & 0.0 & 8.0 & 0.0 & 9.0 \\ \end{pmatrix}\end{split}\]

with the blocks \(A_{ij}\)

\[\begin{split}A_{00} = \begin{pmatrix} 1.0 & 0.0 & 0.0 \\ 3.0 & 0.0 & 4.0 \\ \end{pmatrix}, A_{01} = \begin{pmatrix} 2.0 & 0.0 & 0.0 \\ 0.0 & 0.0 & 0.0 \\ \end{pmatrix}, A_{10} = \begin{pmatrix} 5.0 & 6.0 & 0.0 \\ 0.0 & 0.0 & 8.0 \\ \end{pmatrix}, A_{11} = \begin{pmatrix} 7.0 & 0.0 & 0.0 \\ 0.0 & 9.0 & 0.0 \\ \end{pmatrix}\end{split}\]

such that

\[\begin{split}A = \begin{pmatrix} A_{00} & A_{01} \\ A_{10} & A_{11} \\ \end{pmatrix}\end{split}\]

with arrays representation

\[\begin{split}\begin{array}{ll} \text{bsr_val}[24] & = \{1.0, 3.0, 0.0, 0.0, 0.0, 4.0, 2.0, 0.0, 0.0, 0.0, 0.0, 0.0, 5.0, 0.0, 6.0, 0.0, 0.0, 8.0, 7.0, 0.0, 0.0, 9.0, 0.0, 0.0\} \\ \text{bsr_row_ptr}[3] & = \{0, 2, 4\} \\ \text{bsr_col_ind}[4] & = \{0, 1, 0, 1\} \end{array}\end{split}\]

### ELL storage format

The Ellpack-Itpack (ELL) storage format represents a \(m \times n\) matrix by

m | number of rows (integer).
n | number of columns (integer).
ell_width | maximum number of non-zero elements per row (integer)
ell_val | array of `m times ell_width` elements containing the data (floating point).
ell_col_ind | array of `m times ell_width` elements containing the column indices (integer).

The ELL matrix is assumed to be stored in column-major format. Rows with less than `ell_width` non-zero elements are padded with zeros (`ell_val`) and \(-1\) (`ell_col_ind`). Consider the following \(3 \times 5\) matrix and the corresponding ELL structures, with \(m = 3, n = 5\) and \(\text{ell_width} = 3\) using zero based indexing:

\[\begin{split}A = \begin{pmatrix} 1.0 & 2.0 & 0.0 & 3.0 & 0.0 \\ 0.0 & 4.0 & 5.0 & 0.0 & 0.0 \\ 6.0 & 0.0 & 0.0 & 7.0 & 8.0 \\ \end{pmatrix}\end{split}\]

where

\[\begin{split}\begin{array}{ll} \text{ell_val}[9] & = \{1.0, 4.0, 6.0, 2.0, 5.0, 7.0, 3.0, 0.0, 8.0\} \\ \text{ell_col_ind}[9] & = \{0, 1, 0, 1, 2, 3, 3, -1, 4\} \end{array}\end{split}\]

### HYB storage format

The Hybrid (HYB) storage format represents a \(m \times n\) matrix by

m | number of rows (integer).
n | number of columns (integer).
nnz | number of non-zero elements of the COO part (integer)
ell_width | maximum number of non-zero elements per row of the ELL part (integer)
ell_val | array of `m times ell_width` elements containing the ELL part data (floating point).
ell_col_ind | array of `m times ell_width` elements containing the ELL part column indices (integer).
coo_val | array of `nnz` elements containing the COO part data (floating point).
coo_row_ind | array of `nnz` elements containing the COO part row indices (integer).
coo_col_ind | array of `nnz` elements containing the COO part column indices (integer).

The HYB format is a combination of the ELL and COO sparse matrix formats. Typically, the regular part of the matrix is stored in ELL storage format, and the irregular part of the matrix is stored in COO storage format. Three different partitioning schemes can be applied when converting a CSR matrix to a matrix in HYB storage format. For further details on the partitioning schemes, see rocsparse_hyb_partition.

## Types

### rocsparse_handle

typedef struct _rocsparse_handle *rocsparse_handle

  Handle to the rocSPARSE library context queue.

  The rocSPARSE handle is a structure holding the rocSPARSE library context. It must be initialized using rocsparse_create_handle() and the returned handle must be passed to all subsequent library function calls. It should be destroyed at the end using rocsparse_destroy_handle().

### rocsparse_mat_descr

typedef struct _rocsparse_mat_descr *rocsparse_mat_descr

  Descriptor of the matrix.

  The rocSPARSE matrix descriptor is a structure holding all properties of a matrix. It must be initialized using rocsparse_create_mat_descr() and the returned descriptor must be passed to all subsequent library calls that involve the matrix. It should be destroyed at the end using rocsparse_destroy_mat_descr().

### rocsparse_mat_info

typedef struct _rocsparse_mat_info *rocsparse_mat_info

  Info structure to hold all matrix meta data.

  The rocSPARSE matrix info is a structure holding all matrix information that is gathered during analysis routines. It must be initialized using rocsparse_create_mat_info() and the returned info structure must be passed to all subsequent library calls that require additional matrix information. It should be destroyed at the end using rocsparse_destroy_mat_info().

### rocsparse_hyb_mat

typedef struct _rocsparse_hyb_mat *rocsparse_hyb_mat

  HYB matrix storage format.

  The rocSPARSE HYB matrix structure holds the HYB matrix. It must be initialized using rocsparse_create_hyb_mat() and the returned HYB matrix must be passed to all subsequent library calls that involve the matrix. It should be destroyed at the end using rocsparse_destroy_hyb_mat().

For more details on the HYB format, see HYB storage format.

### rocsparse_action

enum rocsparse_action

  Specify where the operation is performed on.

  The rocsparse_action indicates whether the operation is performed on the full matrix, or only on the sparsity pattern of the matrix.

  Values:

  enumerator rocsparse_action_symbolic

    Operate only on indices.

  enumerator rocsparse_action_numeric

    Operate on data and indices.

### rocsparse_direction

enum rocsparse_direction

  Specify the matrix direction.

  The rocsparse_direction indicates whether a dense matrix should be parsed by rows or by columns, assuming column-major storage.

  Values:

  enumerator rocsparse_direction_row

    Parse the matrix by rows.

  enumerator rocsparse_direction_column

    Parse the matrix by columns.

### rocsparse_hyb_partition

enum rocsparse_hyb_partition

  HYB matrix partitioning type.

  The rocsparse_hyb_partition type indicates how the hybrid format partitioning between COO and ELL storage formats is performed.

  Values:

  enumerator rocsparse_hyb_partition_auto

    automatically decide on ELL nnz per row.

  enumerator rocsparse_hyb_partition_user

    user given ELL nnz per row.

  enumerator rocsparse_hyb_partition_max

    max ELL nnz per row, no COO part.

### rocsparse_index_base

enum rocsparse_index_base

  Specify the matrix index base.

  The rocsparse_index_base indicates the index base of the indices. For a given rocsparse_mat_descr, the rocsparse_index_base can be set using rocsparse_set_mat_index_base(). The current rocsparse_index_base of a matrix can be obtained by rocsparse_get_mat_index_base().

  Values:

  enumerator rocsparse_index_base_zero

    zero based indexing.

  enumerator rocsparse_index_base_one

    one based indexing.

### rocsparse_matrix_type

enum rocsparse_matrix_type

  Specify the matrix type.

  The rocsparse_matrix_type indices the type of a matrix. For a given rocsparse_mat_descr, the rocsparse_matrix_type can be set using rocsparse_set_mat_type(). The current rocsparse_matrix_type of a matrix can be obtained by rocsparse_get_mat_type().

  Values:

  enumerator rocsparse_matrix_type_general

    general matrix type.

  enumerator rocsparse_matrix_type_symmetric

    symmetric matrix type.

  enumerator rocsparse_matrix_type_hermitian

    hermitian matrix type.

  enumerator rocsparse_matrix_type_triangular

    triangular matrix type.

### rocsparse_fill_mode

enum rocsparse_fill_mode

  Specify the matrix fill mode.

  The rocsparse_fill_mode indicates whether the lower or the upper part is stored in a sparse triangular matrix. For a given rocsparse_mat_descr, the rocsparse_fill_mode can be set using rocsparse_set_mat_fill_mode(). The current rocsparse_fill_mode of a matrix can be obtained by rocsparse_get_mat_fill_mode().

  Values:

  enumerator rocsparse_fill_mode_lower

    lower triangular part is stored.

  enumerator rocsparse_fill_mode_upper

    upper triangular part is stored.

### rocsparse_storage_mode

enum rocsparse_storage_mode

  Specify whether the matrix is stored sorted or not.

  The rocsparse_storage_mode indicates whether the matrix is stored sorted or not. For a given rocsparse_mat_descr, the rocsparse_storage_mode can be set using rocsparse_set_storage_mode(). The current rocsparse_storage_mode of a matrix can be obtained by rocsparse_get_mat_storage_mode().

  Values:

  enumerator rocsparse_storage_mode_sorted

    matrix is sorted.

  enumerator rocsparse_storage_mode_unsorted

    matrix is unsorted.

### rocsparse_diag_type

enum rocsparse_diag_type

  Indicates if the diagonal entries are unity.

  The rocsparse_diag_type indicates whether the diagonal entries of a matrix are unity or not. If rocsparse_diag_type_unit is specified, all present diagonal values will be ignored. For a given rocsparse_mat_descr, the rocsparse_diag_type can be set using rocsparse_set_mat_diag_type(). The current rocsparse_diag_type of a matrix can be obtained by rocsparse_get_mat_diag_type().

  Values:

  enumerator rocsparse_diag_type_non_unit

    diagonal entries are non-unity.

  enumerator rocsparse_diag_type_unit

    diagonal entries are unity

### rocsparse_operation

enum rocsparse_operation

  Specify whether the matrix is to be transposed or not.

  The rocsparse_operation indicates the operation performed with the given matrix.

  Values:

  enumerator rocsparse_operation_none

    Operate with matrix.

  enumerator rocsparse_operation_transpose

    Operate with transpose.

  enumerator rocsparse_operation_conjugate_transpose

    Operate with conj. transpose.

### rocsparse_pointer_mode

enum rocsparse_pointer_mode

  Indicates if the pointer is device pointer or host pointer.

  The rocsparse_pointer_mode indicates whether scalar values are passed by reference on the host or device. The rocsparse_pointer_mode can be changed by rocsparse_set_pointer_mode(). The currently used pointer mode can be obtained by rocsparse_get_pointer_mode().

  Values:

  enumerator rocsparse_pointer_mode_host

    scalar pointers are in host memory.

  enumerator rocsparse_pointer_mode_device

    scalar pointers are in device memory.

### rocsparse_analysis_policy

enum rocsparse_analysis_policy

  Specify policy in analysis functions.

  The rocsparse_analysis_policy specifies whether gathered analysis data should be re-used or not. If meta data from a previous e.g. rocsparse_csrilu0_analysis() call is available, it can be re-used for subsequent calls to e.g. rocsparse_csrsv_analysis() and greatly improve performance of the analysis function.

  Values:

  enumerator rocsparse_analysis_policy_reuse

    try to re-use meta data.

  enumerator rocsparse_analysis_policy_force

    force to re-build meta data.

### rocsparse_solve_policy

enum rocsparse_solve_policy

  Specify policy in triangular solvers and factorizations.

  This is a placeholder.

  Values:

  enumerator rocsparse_solve_policy_auto

    automatically decide on level information.

### rocsparse_layer_mode

enum rocsparse_layer_mode

  Indicates if layer is active with bitmask.

  The rocsparse_layer_mode bit mask indicates the logging characteristics.

  Values:

  enumerator rocsparse_layer_mode_none

    layer is not active.

  enumerator rocsparse_layer_mode_log_trace

    layer is in logging mode.

  enumerator rocsparse_layer_mode_log_bench

    layer is in benchmarking mode.

  enumerator rocsparse_layer_mode_log_debug

    layer is in debug mode.

For more details on logging, see Logging.

### rocsparse_status

enum rocsparse_status

  List of rocsparse status codes definition.

  This is a list of the rocsparse_status types that are used by the rocSPARSE library.

  Values:

  enumerator rocsparse_status_success

    success.

  enumerator rocsparse_status_invalid_handle

    handle not initialized, invalid or null.

  enumerator rocsparse_status_not_implemented

    function is not implemented.

  enumerator rocsparse_status_invalid_pointer

    invalid pointer parameter.

  enumerator rocsparse_status_invalid_size

    invalid size parameter.

  enumerator rocsparse_status_memory_error

    failed memory allocation, copy, dealloc.

  enumerator rocsparse_status_internal_error

    other internal library failure.

  enumerator rocsparse_status_invalid_value

    invalid value parameter.

  enumerator rocsparse_status_arch_mismatch

    device arch is not supported.

  enumerator rocsparse_status_zero_pivot

    encountered zero pivot.

  enumerator rocsparse_status_not_initialized

    descriptor has not been initialized.

  enumerator rocsparse_status_type_mismatch

    index types do not match.

  enumerator rocsparse_status_requires_sorted_storage

    sorted storage required.

  enumerator rocsparse_status_thrown_exception

    exception being thrown.

### rocsparse_indextype

enum rocsparse_indextype

  List of rocsparse index types.

  Indicates the index width of a rocsparse index type.

  Values:

  enumerator rocsparse_indextype_u16

    16 bit unsigned integer.

  enumerator rocsparse_indextype_i32

    32 bit signed integer.

  enumerator rocsparse_indextype_i64

    64 bit signed integer.

### rocsparse_datatype

enum rocsparse_datatype

  List of rocsparse data types.

  Indicates the precision width of data stored in a rocsparse type.

  Values:

  enumerator rocsparse_datatype_f32_r

    32 bit floating point, real.

  enumerator rocsparse_datatype_f64_r

    64 bit floating point, real.

  enumerator rocsparse_datatype_f32_c

    32 bit floating point, complex.

  enumerator rocsparse_datatype_f64_c

    64 bit floating point, complex.

  enumerator rocsparse_datatype_i8_r

    8-bit signed integer, real

  enumerator rocsparse_datatype_u8_r

    8-bit unsigned integer, real

  enumerator rocsparse_datatype_i32_r

    32-bit signed integer, real

  enumerator rocsparse_datatype_u32_r

    32-bit unsigned integer, real

### rocsparse_format

enum rocsparse_format

  List of sparse matrix formats.

  This is a list of supported rocsparse_format types that are used to describe a sparse matrix.

  Values:

  enumerator rocsparse_format_coo

    COO sparse matrix format.

  enumerator rocsparse_format_coo_aos

    COO AoS sparse matrix format.

  enumerator rocsparse_format_csr

    CSR sparse matrix format.

  enumerator rocsparse_format_csc

    CSC sparse matrix format.

  enumerator rocsparse_format_ell

    ELL sparse matrix format.

  enumerator rocsparse_format_bell

    BLOCKED ELL sparse matrix format.

  enumerator rocsparse_format_bsr

    BSR sparse matrix format.

### rocsparse_order

enum rocsparse_order

  List of dense matrix ordering.

  This is a list of supported rocsparse_order types that are used to describe the memory layout of a dense matrix

  Values:

  enumerator rocsparse_order_row

    Row major.

  enumerator rocsparse_order_column

    Column major.

### rocsparse_spmv_alg

enum rocsparse_spmv_alg

  List of SpMV algorithms.

  This is a list of supported rocsparse_spmv_alg types that are used to perform matrix vector product.

  Values:

  enumerator rocsparse_spmv_alg_default

    Default SpMV algorithm for the given format.

  enumerator rocsparse_spmv_alg_coo

    COO SpMV algorithm 1 (segmented) for COO matrices.

  enumerator rocsparse_spmv_alg_csr_adaptive

    CSR SpMV algorithm 1 (adaptive) for CSR matrices.

  enumerator rocsparse_spmv_alg_csr_stream

    CSR SpMV algorithm 2 (stream) for CSR matrices.

  enumerator rocsparse_spmv_alg_ell

    ELL SpMV algorithm for ELL matrices.

  enumerator rocsparse_spmv_alg_coo_atomic

    COO SpMV algorithm 2 (atomic) for COO matrices.

  enumerator rocsparse_spmv_alg_bsr

    BSR SpMV algorithm 1 for BSR matrices.

### rocsparse_spmv_stage

enum rocsparse_spmv_stage

  List of SpMV stages.

  This is a list of possible stages during SpMV computation. Typical order is rocsparse_spmv_buffer_size, rocsparse_spmv_preprocess, rocsparse_spmv_compute.

  Values:

  enumerator rocsparse_spmv_stage_auto

    Automatic stage detection.

  enumerator rocsparse_spmv_stage_buffer_size

    Returns the required buffer size.

  enumerator rocsparse_spmv_stage_preprocess

    Preprocess data.

  enumerator rocsparse_spmv_stage_compute

    Performs the actual SpMV computation.

### rocsparse_spsv_alg

enum rocsparse_spsv_alg

  List of SpSV algorithms.

  This is a list of supported rocsparse_spsv_alg types that are used to perform triangular solve.

  Values:

  enumerator rocsparse_spsv_alg_default

    Default SpSV algorithm for the given format.

### rocsparse_spsv_stage

enum rocsparse_spsv_stage

  List of SpSV stages.

  This is a list of possible stages during SpSV computation. Typical order is rocsparse_spsv_buffer_size, rocsparse_spsv_preprocess, rocsparse_spsv_compute.

  Values:

  enumerator rocsparse_spsv_stage_auto

    Automatic stage detection.

  enumerator rocsparse_spsv_stage_buffer_size

    Returns the required buffer size.

  enumerator rocsparse_spsv_stage_preprocess

    Preprocess data.

  enumerator rocsparse_spsv_stage_compute

    Performs the actual SpSV computation.

### rocsparse_spsm_alg

enum rocsparse_spsm_alg

  List of SpSM algorithms.

  This is a list of supported rocsparse_spsm_alg types that are used to perform triangular solve.

  Values:

  enumerator rocsparse_spsm_alg_default

    Default SpSM algorithm for the given format.

### rocsparse_spsm_stage

enum rocsparse_spsm_stage

  List of SpSM stages.

  This is a list of possible stages during SpSM computation. Typical order is rocsparse_spsm_buffer_size, rocsparse_spsm_preprocess, rocsparse_spsm_compute.

  Values:

  enumerator rocsparse_spsm_stage_auto

    Automatic stage detection.

  enumerator rocsparse_spsm_stage_buffer_size

    Returns the required buffer size.

  enumerator rocsparse_spsm_stage_preprocess

    Preprocess data.

  enumerator rocsparse_spsm_stage_compute

    Performs the actual SpSM computation.

### rocsparse_spmm_alg

enum rocsparse_spmm_alg

  List of SpMM algorithms.

  This is a list of supported rocsparse_spmm_alg types that are used to perform matrix vector product.

  Values:

  enumerator rocsparse_spmm_alg_default

    Default SpMM algorithm for the given format.

  enumerator rocsparse_spmm_alg_csr

    SpMM algorithm for CSR format using row split and shared memory.

  enumerator rocsparse_spmm_alg_coo_segmented

    SpMM algorithm for COO format using segmented scan.

  enumerator rocsparse_spmm_alg_coo_atomic

    SpMM algorithm for COO format using atomics.

  enumerator rocsparse_spmm_alg_csr_row_split

    SpMM algorithm for CSR format using row split and shfl.

  enumerator rocsparse_spmm_alg_csr_merge

    SpMM algorithm for CSR format using conversion to COO.

  enumerator rocsparse_spmm_alg_coo_segmented_atomic

    SpMM algorithm for COO format using segmented scan and atomics.

  enumerator rocsparse_spmm_alg_bell

    SpMM algorithm for Blocked ELL format.

  enumerator rocsparse_spmm_alg_bsr

    SpMM algorithm for BSR format.

### rocsparse_spmm_stage

enum rocsparse_spmm_stage

  List of SpMM stages.

  This is a list of possible stages during SpMM computation. Typical order is rocsparse_spmm_buffer_size, rocsparse_spmm_preprocess, rocsparse_spmm_compute.

  Values:

  enumerator rocsparse_spmm_stage_auto

    Automatic stage detection.

  enumerator rocsparse_spmm_stage_buffer_size

    Returns the required buffer size.

  enumerator rocsparse_spmm_stage_preprocess

    Preprocess data.

  enumerator rocsparse_spmm_stage_compute

    Performs the actual SpMM computation.

### rocsparse_sddmm_alg

enum rocsparse_sddmm_alg

  List of sddmm algorithms.

  This is a list of supported rocsparse_sddmm_alg types that are used to perform matrix vector product.

  Values:

  enumerator rocsparse_sddmm_alg_default

    Default sddmm algorithm for the given format.

### rocsparse_spgemm_stage

enum rocsparse_spgemm_stage

  List of SpGEMM stages.

  This is a list of possible stages during SpGEMM computation. Typical order is rocsparse_spgemm_buffer_size, rocsparse_spgemm_nnz, rocsparse_spgemm_compute.

  Values:

  enumerator rocsparse_spgemm_stage_auto

    Automatic stage detection.

  enumerator rocsparse_spgemm_stage_buffer_size

    Returns the required buffer size.

  enumerator rocsparse_spgemm_stage_nnz

    Computes number of non-zero entries.

  enumerator rocsparse_spgemm_stage_compute

    Performs the actual SpGEMM computation.

  enumerator rocsparse_spgemm_stage_symbolic

    Performs the actual SpGEMM symbolic computation.

  enumerator rocsparse_spgemm_stage_numeric

    Performs the actual SpGEMM numeric computation.

### rocsparse_spgemm_alg

enum rocsparse_spgemm_alg

  List of SpGEMM algorithms.

  This is a list of supported rocsparse_spgemm_alg types that are used to perform sparse matrix sparse matrix product.

  Values:

  enumerator rocsparse_spgemm_alg_default

    Default SpGEMM algorithm for the given format.

### rocsparse_sparse_to_dense_alg

enum rocsparse_sparse_to_dense_alg

  List of sparse to dense algorithms.

  This is a list of supported rocsparse_sparse_to_dense_alg types that are used to perform sparse to dense conversion.

  Values:

  enumerator rocsparse_sparse_to_dense_alg_default

    Default sparse to dense algorithm for the given format.

### rocsparse_dense_to_sparse_alg

enum rocsparse_dense_to_sparse_alg

  List of dense to sparse algorithms.

  This is a list of supported rocsparse_dense_to_sparse_alg types that are used to perform dense to sparse conversion.

  Values:

  enumerator rocsparse_dense_to_sparse_alg_default

    Default dense to sparse algorithm for the given format.

### rocsparse_gtsv_interleaved_alg

enum rocsparse_gtsv_interleaved_alg

  List of interleaved gtsv algorithms.

  This is a list of supported rocsparse_gtsv_interleaved_alg types that are used to perform interleaved tridiagonal solve.

  Values:

  enumerator rocsparse_gtsv_interleaved_alg_default

    Solve interleaved gtsv using QR algorithm (stable).

  enumerator rocsparse_gtsv_interleaved_alg_thomas

    Solve interleaved gtsv using thomas algorithm (unstable).

  enumerator rocsparse_gtsv_interleaved_alg_lu

    Solve interleaved gtsv using LU algorithm (stable).

  enumerator rocsparse_gtsv_interleaved_alg_qr

    Solve interleaved gtsv using QR algorithm (stable).

## Logging

Three different environment variables can be set to enable logging in rocSPARSE: `ROCSPARSE_LAYER`, `ROCSPARSE_LOG_TRACE_PATH`, `ROCSPARSE_LOG_BENCH_PATH` and `ROCSPARSE_LOG_DEBUG_PATH`.

`ROCSPARSE_LAYER` is a bit mask, where several logging modes (rocsparse_layer_mode) can be combined as follows:

`ROCSPARSE_LAYER` unset | logging is disabled.
`ROCSPARSE_LAYER` set to `1` | trace logging is enabled.
`ROCSPARSE_LAYER` set to `2` | bench logging is enabled.
`ROCSPARSE_LAYER` set to `3` | trace logging and bench logging is enabled.
`ROCSPARSE_LAYER` set to `4` | debug logging is enabled.
`ROCSPARSE_LAYER` set to `5` | trace logging and debug logging is enabled.
`ROCSPARSE_LAYER` set to `6` | bench logging and debug logging is enabled.
`ROCSPARSE_LAYER` set to `7` | trace logging and bench logging and debug logging is enabled.

When logging is enabled, each rocSPARSE function call will write the function name as well as function arguments to the logging stream. The default logging stream is `stderr`.

If the user sets the environment variable `ROCSPARSE_LOG_TRACE_PATH` to the full path name for a file, the file is opened and trace logging is streamed to that file. If the user sets the environment variable `ROCSPARSE_LOG_BENCH_PATH` to the full path name for a file, the file is opened and bench logging is streamed to that file. If the file cannot be opened, logging output is stream to `stderr`.

Note that performance will degrade when logging is enabled. By default, the environment variable `ROCSPARSE_LAYER` is unset and logging is disabled.

## Exported Sparse Functions

### Auxiliary Functions

Function name
`rocsparse_create_handle()`
`rocsparse_destroy_handle()`
`rocsparse_set_stream()`
`rocsparse_get_stream()`
`rocsparse_set_pointer_mode()`
`rocsparse_get_pointer_mode()`
`rocsparse_get_version()`
`rocsparse_get_git_rev()`
`rocsparse_create_mat_descr()`
`rocsparse_destroy_mat_descr()`
`rocsparse_copy_mat_descr()`
`rocsparse_set_mat_index_base()`
`rocsparse_get_mat_index_base()`
`rocsparse_set_mat_type()`
`rocsparse_get_mat_type()`
`rocsparse_set_mat_fill_mode()`
`rocsparse_get_mat_fill_mode()`
`rocsparse_set_mat_diag_type()`
`rocsparse_get_mat_diag_type()`
`rocsparse_set_mat_storage_mode()`
`rocsparse_get_mat_storage_mode()`
`rocsparse_create_hyb_mat()`
`rocsparse_destroy_hyb_mat()`
`rocsparse_copy_hyb_mat()`
`rocsparse_create_mat_info()`
`rocsparse_copy_mat_info()`
`rocsparse_destroy_mat_info()`
`rocsparse_create_color_info()`
`rocsparse_destroy_color_info()`
`rocsparse_copy_color_info()`
`rocsparse_create_spvec_descr()`
`rocsparse_destroy_spvec_descr()`
`rocsparse_spvec_get()`
`rocsparse_spvec_get_index_base()`
`rocsparse_spvec_get_values()`
`rocsparse_spvec_set_values()`
`rocsparse_create_coo_descr()`
`rocsparse_create_coo_aos_descr()`
`rocsparse_create_csr_descr()`
`rocsparse_create_csc_descr()`
`rocsparse_create_ell_descr()`
`rocsparse_create_bell_descr()`
`rocsparse_destroy_spmat_descr()`
`rocsparse_coo_get()`
`rocsparse_coo_aos_get()`
`rocsparse_csr_get()`
`rocsparse_ell_get()`
`rocsparse_bell_get()`
`rocsparse_coo_set_pointers()`
`rocsparse_coo_aos_set_pointers()`
`rocsparse_csr_set_pointers()`
`rocsparse_csc_set_pointers()`
`rocsparse_ell_set_pointers()`
`rocsparse_bsr_set_pointers()`
`rocsparse_spmat_get_size()`
`rocsparse_spmat_get_format()`
`rocsparse_spmat_get_index_base()`
`rocsparse_spmat_get_values()`
`rocsparse_spmat_set_values()`
`rocsparse_spmat_get_strided_batch()`
`rocsparse_spmat_set_strided_batch()`
`rocsparse_coo_set_strided_batch()`
`rocsparse_csr_set_strided_batch()`
`rocsparse_csc_set_strided_batch()`
`rocsparse_spmat_get_attribute()`
`rocsparse_spmat_set_attribute()`
`rocsparse_create_dnvec_descr()`
`rocsparse_destroy_dnvec_descr()`
`rocsparse_dnvec_get()`
`rocsparse_dnvec_get_values()`
`rocsparse_dnvec_set_values()`
`rocsparse_create_dnmat_descr()`
`rocsparse_destroy_dnmat_descr()`
`rocsparse_dnmat_get()`
`rocsparse_dnmat_get_values()`
`rocsparse_dnmat_set_values()`
`rocsparse_dnmat_get_strided_batch()`
`rocsparse_dnmat_set_strided_batch()`

### Sparse Level 1 Functions

Function name | single | double | single complex | double complex
--- | --- | --- | --- | ---
`rocsparse_Xaxpyi()` | x | x | x | x
`rocsparse_Xdoti()` | x | x | x | x
`rocsparse_Xdotci()` |  |  | x | x
`rocsparse_Xgthr()` | x | x | x | x
`rocsparse_Xgthrz()` | x | x | x | x
`rocsparse_Xroti()` | x | x |  |
`rocsparse_Xsctr()` | x | x | x | x

### Sparse Level 2 Functions

Function name | single | double | single complex | double complex
--- | --- | --- | --- | ---
`rocsparse_Xbsrmv_ex_analysis()` | x | x | x | x
`rocsparse_bsrmv_ex_clear()` |  |  |  |
`rocsparse_Xbsrmv_ex()` | x | x | x | x
`rocsparse_Xbsrmv()` | x | x | x | x
`rocsparse_Xbsrxmv()` | x | x | x | x
`rocsparse_Xbsrsv_buffer_size()` | x | x | x | x
`rocsparse_Xbsrsv_analysis()` | x | x | x | x
`rocsparse_bsrsv_zero_pivot()` |  |  |  |
`rocsparse_bsrsv_clear()` |  |  |  |
`rocsparse_Xbsrsv_solve()` | x | x | x | x
`rocsparse_Xcoomv()` | x | x | x | x
`rocsparse_Xcsrmv_analysis()` | x | x | x | x
`rocsparse_csrmv_clear()` |  |  |  |
`rocsparse_Xcsrmv()` | x | x | x | x
`rocsparse_Xcsrsv_buffer_size()` | x | x | x | x
`rocsparse_Xcsrsv_analysis()` | x | x | x | x
`rocsparse_csrsv_zero_pivot()` |  |  |  |
`rocsparse_csrsv_clear()` |  |  |  |
`rocsparse_Xcsrsv_solve()` | x | x | x | x
`rocsparse_Xcsritsv_buffer_size()` | x | x | x | x
`rocsparse_Xcsritsv_analysis()` | x | x | x | x
`rocsparse_csritsv_zero_pivot()` |  |  |  |
`rocsparse_csritsv_clear()` |  |  |  |
`rocsparse_Xcsritsv_solve()` | x | x | x | x
`rocsparse_Xellmv()` | x | x | x | x
`rocsparse_Xhybmv()` | x | x | x | x
`rocsparse_Xgebsrmv()` | x | x | x | x
`rocsparse_Xgemvi_buffer_size()` | x | x | x | x
`rocsparse_Xgemvi()` | x | x | x | x

### Sparse Level 3 Functions

Function name | single | double | single complex | double complex
--- | --- | --- | --- | ---
`rocsparse_Xbsrmm()` | x | x | x | x
`rocsparse_Xgebsrmm()` | x | x | x | x
`rocsparse_Xcsrmm()` | x | x | x | x
`rocsparse_Xcsrsm_buffer_size()` | x | x | x | x
`rocsparse_Xcsrsm_analysis()` | x | x | x | x
`rocsparse_csrsm_zero_pivot()` |  |  |  |
`rocsparse_csrsm_clear()` |  |  |  |
`rocsparse_Xcsrsm_solve()` | x | x | x | x
`rocsparse_Xbsrsm_buffer_size()` | x | x | x | x
`rocsparse_Xbsrsm_analysis()` | x | x | x | x
`rocsparse_bsrsm_zero_pivot()` |  |  |  |
`rocsparse_bsrsm_clear()` |  |  |  |
`rocsparse_Xbsrsm_solve()` | x | x | x | x
`rocsparse_Xgemmi()` | x | x | x | x

### Sparse Extra Functions

Function name | single | double | single complex | double complex
--- | --- | --- | --- | ---
`rocsparse_bsrgeam_nnzb()` |  |  |  |
`rocsparse_Xbsrgeam()` | x | x | x | x
`rocsparse_Xbsrgemm_buffer_size()` | x | x | x | x
`rocsparse_bsrgemm_nnz()` |  |  |  |
`rocsparse_Xbsrgemm()` | x | x | x | x
`rocsparse_csrgeam_nnz()` |  |  |  |
`rocsparse_Xcsrgeam()` | x | x | x | x
`rocsparse_Xcsrgemm_buffer_size()` | x | x | x | x
`rocsparse_csrgemm_nnz()` |  |  |  |
`rocsparse_csrgemm_symbolic()` |  |  |  |
`rocsparse_Xcsrgemm()` | x | x | x | x
`rocsparse_Xcsrgemm_numeric()` | x | x | x | x

### Preconditioner Functions

Function name | single | double | single complex | double complex
--- | --- | --- | --- | ---
`rocsparse_Xbsric0_buffer_size()` | x | x | x | x
`rocsparse_Xbsric0_analysis()` | x | x | x | x
`rocsparse_bsric0_zero_pivot()` |  |  |  |
`rocsparse_bsric0_clear()` |  |  |  |
`rocsparse_Xbsric0()` | x | x | x | x
`rocsparse_Xbsrilu0_buffer_size()` | x | x | x | x
`rocsparse_Xbsrilu0_analysis()` | x | x | x | x
`rocsparse_bsrilu0_zero_pivot()` |  |  |  |
`rocsparse_Xbsrilu0_numeric_boost()` | x | x | x | x
`rocsparse_bsrilu0_clear()` |  |  |  |
`rocsparse_Xbsrilu0()` | x | x | x | x
`rocsparse_Xcsric0_buffer_size()` | x | x | x | x
`rocsparse_Xcsric0_analysis()` | x | x | x | x
`rocsparse_csric0_zero_pivot()` |  |  |  |
`rocsparse_csric0_clear()` |  |  |  |
`rocsparse_Xcsric0()` | x | x | x | x
`rocsparse_Xcsrilu0_buffer_size()` | x | x | x | x
`rocsparse_Xcsrilu0_numeric_boost()` | x | x | x | x
`rocsparse_Xcsrilu0_analysis()` | x | x | x | x
`rocsparse_csrilu0_zero_pivot()` |  |  |  |
`rocsparse_csrilu0_clear()` |  |  |  |
`rocsparse_Xcsrilu0()` | x | x | x | x
`rocsparse_csritilu0_buffer_size()` |  |  |  |
`rocsparse_csritilu0_preprocess()` |  |  |  |
`rocsparse_Xcsritilu0_compute()` | x | x | x | x
`rocsparse_Xcsritilu0_history()` | x | x | x | x
`rocsparse_Xgtsv_buffer_size()` | x | x | x | x
`rocsparse_Xgtsv()` | x | x | x | x
`rocsparse_Xgtsv_no_pivot_buffer_size()` | x | x | x | x
`rocsparse_Xgtsv_no_pivot()` | x | x | x | x
`rocsparse_Xgtsv_no_pivot_strided_batch_buffer_size()` | x | x | x | x
`rocsparse_Xgtsv_no_pivot_strided_batch()` | x | x | x | x
`rocsparse_Xgtsv_interleaved_batch_buffer_size()` | x | x | x | x
`rocsparse_Xgtsv_interleaved_batch()` | x | x | x | x
`rocsparse_Xgpsv_interleaved_batch_buffer_size()` | x | x | x | x
`rocsparse_Xgpsv_interleaved_batch()` | x | x | x | x

### Conversion Functions

Function name | single | double | single complex | double complex
--- | --- | --- | --- | ---
`rocsparse_csr2coo()` |  |  |  |
`rocsparse_csr2csc_buffer_size()` |  |  |  |
`rocsparse_Xcsr2csc()` | x | x | x | x
`rocsparse_Xgebsr2gebsc_buffer_size()` | x | x | x | x
`rocsparse_Xgebsr2gebsc()` | x | x | x | x
`rocsparse_csr2ell_width()` |  |  |  |
`rocsparse_Xcsr2ell()` | x | x | x | x
`rocsparse_Xcsr2hyb()` | x | x | x | x
`rocsparse_csr2bsr_nnz()` |  |  |  |
`rocsparse_Xcsr2bsr()` | x | x | x | x
`rocsparse_csr2gebsr_nnz()` |  |  |  |
`rocsparse_Xcsr2gebsr_buffer_size()` | x | x | x | x
`rocsparse_Xcsr2gebsr()` | x | x | x | x
`rocsparse_coo2csr()` |  |  |  |
`rocsparse_ell2csr_nnz()` |  |  |  |
`rocsparse_Xell2csr()` | x | x | x | x
`rocsparse_hyb2csr_buffer_size()` |  |  |  |
`rocsparse_Xhyb2csr()` | x | x | x | x
`rocsparse_Xbsr2csr()` | x | x | x | x
`rocsparse_Xgebsr2csr()` | x | x | x | x
`rocsparse_Xgebsr2gebsr_buffer_size()` | x | x | x | x
`rocsparse_gebsr2gebsr_nnz()` |  |  |  |
`rocsparse_Xgebsr2gebsr()` | x | x | x | x
`rocsparse_Xcsr2csr_compress()` | x | x | x | x
`rocsparse_create_identity_permutation()` |  |  |  |
`rocsparse_cscsort_buffer_size()` |  |  |  |
`rocsparse_cscsort()` |  |  |  |
`rocsparse_csrsort_buffer_size()` |  |  |  |
`rocsparse_csrsort()` |  |  |  |
`rocsparse_coosort_buffer_size()` |  |  |  |
`rocsparse_coosort_by_row()` |  |  |  |
`rocsparse_coosort_by_column()` |  |  |  |
`rocsparse_Xdense2csr()` | x | x | x | x
`rocsparse_Xdense2csc()` | x | x | x | x
`rocsparse_Xdense2coo()` | x | x | x | x
`rocsparse_Xcsr2dense()` | x | x | x | x
`rocsparse_Xcsc2dense()` | x | x | x | x
`rocsparse_Xcoo2dense()` | x | x | x | x
`rocsparse_Xnnz_compress()` | x | x | x | x
`rocsparse_Xnnz()` | x | x | x | x
`rocsparse_Xprune_dense2csr_buffer_size()` | x | x |  |
`rocsparse_Xprune_dense2csr_nnz()` | x | x |  |
`rocsparse_Xprune_dense2csr()` | x | x |  |
`rocsparse_Xprune_csr2csr_buffer_size()` | x | x |  |
`rocsparse_Xprune_csr2csr_nnz()` | x | x |  |
`rocsparse_Xprune_csr2csr()` | x | x |  |
`rocsparse_Xprune_dense2csr_by_percentage_buffer_size()` | x | x |  |
`rocsparse_Xprune_dense2csr_nnz_by_percentage()` | x | x |  |
`rocsparse_Xprune_dense2csr_by_percentage()` | x | x |  |
`rocsparse_Xprune_csr2csr_by_percentage_buffer_size()` | x | x |  |
`rocsparse_Xprune_csr2csr_nnz_by_percentage()` | x | x |  |
`rocsparse_Xprune_csr2csr_by_percentage()` | x | x |  |
`rocsparse_Xbsrpad_value()` | x | x | x | x

### Reordering Functions

Function name | single | double | single complex | double complex
--- | --- | --- | --- | ---
`rocsparse_Xcsrcolor()` | x | x | x | x

### Utility Functions

Function name | single | double | single complex | double complex
--- | --- | --- | --- | ---
`rocsparse_Xcheck_matrix_csr_buffer_size()` | x | x | x | x
`rocsparse_Xcheck_matrix_csr()` | x | x | x | x
`rocsparse_Xcheck_matrix_csc_buffer_size()` | x | x | x | x
`rocsparse_Xcheck_matrix_csc()` | x | x | x | x
`rocsparse_Xcheck_matrix_coo_buffer_size()` | x | x | x | x
`rocsparse_Xcheck_matrix_coo()` | x | x | x | x
`rocsparse_Xcheck_matrix_gebsr_buffer_size()` | x | x | x | x
`rocsparse_Xcheck_matrix_gebsr()` | x | x | x | x
`rocsparse_Xcheck_matrix_gebsc_buffer_size()` | x | x | x | x
`rocsparse_Xcheck_matrix_gebsc()` | x | x | x | x
`rocsparse_Xcheck_matrix_ell_buffer_size()` | x | x | x | x
`rocsparse_Xcheck_matrix_ell()` | x | x | x | x
`rocsparse_check_matrix_hyb_buffer_size()` | x | x | x | x
`rocsparse_check_matrix_hyb()` | x | x | x | x

### Sparse Generic Functions

Function name | single | double | single complex | double complex
--- | --- | --- | --- | ---
`rocsparse_axpby()` | x | x | x | x
`rocsparse_gather()` | x | x | x | x
`rocsparse_scatter()` | x | x | x | x
`rocsparse_rot()` | x | x | x | x
`rocsparse_spvv()` | x | x | x | x
`rocsparse_sparse_to_dense()` | x | x | x | x
`rocsparse_dense_to_sparse()` | x | x | x | x
`rocsparse_spmv()` | x | x | x | x
`rocsparse_spmv_ex()` | x | x | x | x
`rocsparse_spsv()` | x | x | x | x
`rocsparse_spmm()` | x | x | x | x
`rocsparse_spmm_ex()` | x | x | x | x
`rocsparse_spsm()` | x | x | x | x
`rocsparse_spgemm()` | x | x | x | x
`rocsparse_sddmm_buffer_size()` | x | x | x | x
`rocsparse_sddmm_preprocess()` | x | x | x | x
`rocsparse_sddmm()` | x | x | x | x

### Storage schemes and indexing base

rocSPARSE supports 0 and 1 based indexing. The index base is selected by the `rocsparse_index_base` type which is either passed as standalone parameter or as part of the `rocsparse_mat_descr` type.

Furthermore, dense vectors are represented with a 1D array, stored linearly in memory. Sparse vectors are represented by a 1D data array stored linearly in memory that hold all non-zero elements and a 1D indexing array stored linearly in memory that hold the positions of the corresponding non-zero elements.

### Pointer mode

The auxiliary functions `rocsparse_set_pointer_mode()` and `rocsparse_get_pointer_mode()` are used to set and get the value of the state variable `rocsparse_pointer_mode`. If `rocsparse_pointer_mode` is equal to `rocsparse_pointer_mode_host`, then scalar parameters must be allocated on the host. If `rocsparse_pointer_mode` is equal to `rocsparse_pointer_mode_device`, then scalar parameters must be allocated on the device.

There are two types of scalar parameter:

> 1. Scaling parameters, such as alpha and beta used in e.g. `rocsparse_scsrmv()`, `rocsparse_scoomv()`, …

> 2. Scalar results from functions such as `rocsparse_sdoti()`, `rocsparse_cdotci()`, …

For scalar parameters such as alpha and beta, memory can be allocated on the host heap or stack, when `rocsparse_pointer_mode` is equal to `rocsparse_pointer_mode_host`. The kernel launch is asynchronous, and if the scalar parameter is on the heap, it can be freed after the return from the kernel launch. When `rocsparse_pointer_mode` is equal to `rocsparse_pointer_mode_device`, the scalar parameter must not be changed till the kernel completes.

For scalar results, when `rocsparse_pointer_mode` is equal to `rocsparse_pointer_mode_host`, the function blocks the CPU till the GPU has copied the result back to the host. Using `rocsparse_pointer_mode` equal to `rocsparse_pointer_mode_device`, the function will return after the asynchronous launch. Similarly to vector and matrix results, the scalar result is only available when the kernel has completed execution.

### Asynchronous API

Except a functions having memory allocation inside preventing asynchronicity, all rocSPARSE functions are configured to operate in non-blocking fashion with respect to CPU, meaning these library functions return immediately.

### hipSPARSE

hipSPARSE is a SPARSE marshalling library, with multiple supported backends. It sits between the application and a worker SPARSE library, marshalling inputs into the backend library and marshalling results back to the application. hipSPARSE exports an interface that does not require the client to change, regardless of the chosen backend. Currently, hipSPARSE supports rocSPARSE and cuSPARSE as backends. hipSPARSE focuses on convenience and portability. If performance outweighs these factors, then using rocSPARSE itself is highly recommended. hipSPARSE can be found on GitHub.

## Sparse Auxiliary Functions

This module holds all sparse auxiliary functions.

The functions that are contained in the auxiliary module describe all available helper functions that are required for subsequent library calls.

The functions in this module do not support execution in a hipGraph context.

### rocsparse_create_handle()

rocsparse_status rocsparse_create_handle(rocsparse_handle *handle)

  Create a rocsparse handle.

  `rocsparse_create_handle` creates the rocSPARSE library context. It must be initialized before any other rocSPARSE API function is invoked and must be passed to all subsequent library function calls. The handle should be destroyed at the end using rocsparse_destroy_handle().

  Parameters:

    handle – [out] the pointer to the handle to the rocSPARSE library context.

  Return values:

    - rocsparse_status_success – the initialization succeeded.

    - rocsparse_status_invalid_handle – `handle` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

### rocsparse_destroy_handle()

rocsparse_status rocsparse_destroy_handle(rocsparse_handle handle)

  Destroy a rocsparse handle.

  `rocsparse_destroy_handle` destroys the rocSPARSE library context and releases all resources used by the rocSPARSE library.

  Parameters:

    handle – [in] the handle to the rocSPARSE library context.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – `handle` is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

### rocsparse_set_stream()

rocsparse_status rocsparse_set_stream(rocsparse_handle handle, hipStream_t stream)

  Specify user defined HIP stream.

  `rocsparse_set_stream` specifies the stream to be used by the rocSPARSE library context and all subsequent function calls.

  Example

    This example illustrates, how a user defined stream can be used in rocSPARSE.

        // Create rocSPARSE handle
        rocsparse_handle handle;
        rocsparse_create_handle(&handle);

        // Create stream
        hipStream_t stream;
        hipStreamCreate(&stream);

        // Set stream to rocSPARSE handle
        rocsparse_set_stream(handle, stream);

        // Do some work
        // ...

        // Clean up
        rocsparse_destroy_handle(handle);
        hipStreamDestroy(stream);

  Parameters:

    - handle – [inout] the handle to the rocSPARSE library context.

    - stream – [in] the stream to be used by the rocSPARSE library context.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – `handle` is invalid.

### rocsparse_get_stream()

rocsparse_status rocsparse_get_stream(rocsparse_handle handle, hipStream_t *stream)

  Get current stream from library context.

  `rocsparse_get_stream` gets the rocSPARSE library context stream which is currently used for all subsequent function calls.

  Parameters:

    - handle – [in] the handle to the rocSPARSE library context.

    - stream – [out] the stream currently used by the rocSPARSE library context.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – `handle` is invalid.

### rocsparse_set_pointer_mode()

rocsparse_status rocsparse_set_pointer_mode(rocsparse_handle handle, rocsparse_pointer_mode pointer_mode)

  Specify pointer mode.

  `rocsparse_set_pointer_mode` specifies the pointer mode to be used by the rocSPARSE library context and all subsequent function calls. By default, all values are passed by reference on the host. Valid pointer modes are rocsparse_pointer_mode_host or `rocsparse_pointer_mode_device`.

  Parameters:

    - handle – [in] the handle to the rocSPARSE library context.

    - pointer_mode – [in] the pointer mode to be used by the rocSPARSE library context.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – `handle` is invalid.

### rocsparse_get_pointer_mode()

rocsparse_status rocsparse_get_pointer_mode(rocsparse_handle handle, rocsparse_pointer_mode *pointer_mode)

  Get current pointer mode from library context.

  `rocsparse_get_pointer_mode` gets the rocSPARSE library context pointer mode which is currently used for all subsequent function calls.

  Parameters:

    - handle – [in] the handle to the rocSPARSE library context.

    - pointer_mode – [out] the pointer mode that is currently used by the rocSPARSE library context.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – `handle` is invalid.

### rocsparse_get_version()

rocsparse_status rocsparse_get_version(rocsparse_handle handle, int *version)

  Get rocSPARSE version.

  `rocsparse_get_version` gets the rocSPARSE library version number.

  - patch = version % 100

  - minor = version / 100 % 1000

  - major = version / 100000

  Parameters:

    - handle – [in] the handle to the rocSPARSE library context.

    - version – [out] the version number of the rocSPARSE library.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – `handle` is invalid.

### rocsparse_get_git_rev()

rocsparse_status rocsparse_get_git_rev(rocsparse_handle handle, char *rev)

  Get rocSPARSE git revision.

  `rocsparse_get_git_rev` gets the rocSPARSE library git commit revision (SHA-1).

  Parameters:

    - handle – [in] the handle to the rocSPARSE library context.

    - rev – [out] the git commit revision (SHA-1).

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – `handle` is invalid.

### rocsparse_create_mat_descr()

rocsparse_status rocsparse_create_mat_descr(rocsparse_mat_descr *descr)

  Create a matrix descriptor.

  `rocsparse_create_mat_descr` creates a matrix descriptor. It initializes rocsparse_matrix_type to rocsparse_matrix_type_general and rocsparse_index_base to rocsparse_index_base_zero. It should be destroyed at the end using rocsparse_destroy_mat_descr().

  Parameters:

    descr – [out] the pointer to the matrix descriptor.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – `descr` pointer is invalid.

### rocsparse_destroy_mat_descr()

rocsparse_status rocsparse_destroy_mat_descr(rocsparse_mat_descr descr)

  Destroy a matrix descriptor.

  `rocsparse_destroy_mat_descr` destroys a matrix descriptor and releases all resources used by the descriptor.

  Parameters:

    descr – [in] the matrix descriptor.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – `descr` is invalid.

### rocsparse_copy_mat_descr()

rocsparse_status rocsparse_copy_mat_descr(rocsparse_mat_descr dest, const rocsparse_mat_descr src)

  Copy a matrix descriptor.

  `rocsparse_copy_mat_descr` copies a matrix descriptor. Both, source and destination matrix descriptors must be initialized prior to calling `rocsparse_copy_mat_descr`.

  Parameters:

    - dest – [out] the pointer to the destination matrix descriptor.

    - src – [in] the pointer to the source matrix descriptor.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – `src` or `dest` pointer is invalid.

### rocsparse_set_mat_index_base()

rocsparse_status rocsparse_set_mat_index_base(rocsparse_mat_descr descr, rocsparse_index_base base)

  Specify the index base of a matrix descriptor.

  `rocsparse_set_mat_index_base` sets the index base of a matrix descriptor. Valid options are rocsparse_index_base_zero or rocsparse_index_base_one.

  Parameters:

    - descr – [inout] the matrix descriptor.

    - base – [in] rocsparse_index_base_zero or rocsparse_index_base_one.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – `descr` pointer is invalid.

    - rocsparse_status_invalid_value – `base` is invalid.

### rocsparse_get_mat_index_base()

rocsparse_index_base rocsparse_get_mat_index_base(const rocsparse_mat_descr descr)

  Get the index base of a matrix descriptor.

  `rocsparse_get_mat_index_base` returns the index base of a matrix descriptor.

  Parameters:

    descr – [in] the matrix descriptor.

  Returns:

    rocsparse_index_base_zero or rocsparse_index_base_one.

### rocsparse_set_mat_type()

rocsparse_status rocsparse_set_mat_type(rocsparse_mat_descr descr, rocsparse_matrix_type type)

  Specify the matrix type of a matrix descriptor.

  `rocsparse_set_mat_type` sets the matrix type of a matrix descriptor. Valid matrix types are rocsparse_matrix_type_general, rocsparse_matrix_type_symmetric, rocsparse_matrix_type_hermitian or rocsparse_matrix_type_triangular.

  Parameters:

    - descr – [inout] the matrix descriptor.

    - type – [in] rocsparse_matrix_type_general, rocsparse_matrix_type_symmetric, rocsparse_matrix_type_hermitian or rocsparse_matrix_type_triangular.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – `descr` pointer is invalid.

    - rocsparse_status_invalid_value – `type` is invalid.

### rocsparse_get_mat_type()

rocsparse_matrix_type rocsparse_get_mat_type(const rocsparse_mat_descr descr)

  Get the matrix type of a matrix descriptor.

  `rocsparse_get_mat_type` returns the matrix type of a matrix descriptor.

  Parameters:

    descr – [in] the matrix descriptor.

  Returns:

    rocsparse_matrix_type_general, rocsparse_matrix_type_symmetric, rocsparse_matrix_type_hermitian or rocsparse_matrix_type_triangular.

### rocsparse_set_mat_fill_mode()

rocsparse_status rocsparse_set_mat_fill_mode(rocsparse_mat_descr descr, rocsparse_fill_mode fill_mode)

  Specify the matrix fill mode of a matrix descriptor.

  `rocsparse_set_mat_fill_mode` sets the matrix fill mode of a matrix descriptor. Valid fill modes are rocsparse_fill_mode_lower or rocsparse_fill_mode_upper.

  Parameters:

    - descr – [inout] the matrix descriptor.

    - fill_mode – [in] rocsparse_fill_mode_lower or rocsparse_fill_mode_upper.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – `descr` pointer is invalid.

    - rocsparse_status_invalid_value – `fill_mode` is invalid.

### rocsparse_get_mat_fill_mode()

rocsparse_fill_mode rocsparse_get_mat_fill_mode(const rocsparse_mat_descr descr)

  Get the matrix fill mode of a matrix descriptor.

  `rocsparse_get_mat_fill_mode` returns the matrix fill mode of a matrix descriptor.

  Parameters:

    descr – [in] the matrix descriptor.

  Returns:

    rocsparse_fill_mode_lower or rocsparse_fill_mode_upper.

### rocsparse_set_mat_diag_type()

rocsparse_status rocsparse_set_mat_diag_type(rocsparse_mat_descr descr, rocsparse_diag_type diag_type)

  Specify the matrix diagonal type of a matrix descriptor.

  `rocsparse_set_mat_diag_type` sets the matrix diagonal type of a matrix descriptor. Valid diagonal types are rocsparse_diag_type_unit or rocsparse_diag_type_non_unit.

  Parameters:

    - descr – [inout] the matrix descriptor.

    - diag_type – [in] rocsparse_diag_type_unit or rocsparse_diag_type_non_unit.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – `descr` pointer is invalid.

    - rocsparse_status_invalid_value – `diag_type` is invalid.

### rocsparse_get_mat_diag_type()

rocsparse_diag_type rocsparse_get_mat_diag_type(const rocsparse_mat_descr descr)

  Get the matrix diagonal type of a matrix descriptor.

  `rocsparse_get_mat_diag_type` returns the matrix diagonal type of a matrix descriptor.

  Parameters:

    descr – [in] the matrix descriptor.

  Returns:

    rocsparse_diag_type_unit or rocsparse_diag_type_non_unit.

### rocsparse_set_mat_storage_mode()

rocsparse_status rocsparse_set_mat_storage_mode(rocsparse_mat_descr descr, rocsparse_storage_mode storage_mode)

  Specify the matrix storage mode of a matrix descriptor.

  `rocsparse_set_mat_storage_mode` sets the matrix storage mode of a matrix descriptor. Valid fill modes are rocsparse_storage_mode_sorted or rocsparse_storage_mode_unsorted.

  Parameters:

    - descr – [inout] the matrix descriptor.

    - storage_mode – [in] rocsparse_storage_mode_sorted or rocsparse_storage_mode_unsorted.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – `descr` pointer is invalid.

    - rocsparse_status_invalid_value – `storage_mode` is invalid.

### rocsparse_get_mat_storage_mode()

rocsparse_storage_mode rocsparse_get_mat_storage_mode(const rocsparse_mat_descr descr)

  Get the matrix storage mode of a matrix descriptor.

  `rocsparse_get_mat_storage_mode` returns the matrix storage mode of a matrix descriptor.

  Parameters:

    descr – [in] the matrix descriptor.

  Returns:

    rocsparse_storage_mode_sorted or rocsparse_storage_mode_unsorted.

### rocsparse_create_hyb_mat()

rocsparse_status rocsparse_create_hyb_mat(rocsparse_hyb_mat *hyb)

  Create a `HYB` matrix structure.

  `rocsparse_create_hyb_mat` creates a structure that holds the matrix in `HYB` storage format. It should be destroyed at the end using rocsparse_destroy_hyb_mat().

  Parameters:

    hyb – [inout] the pointer to the hybrid matrix.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – `hyb` pointer is invalid.

### rocsparse_destroy_hyb_mat()

rocsparse_status rocsparse_destroy_hyb_mat(rocsparse_hyb_mat hyb)

  Destroy a `HYB` matrix structure.

  `rocsparse_destroy_hyb_mat` destroys a `HYB` structure.

  Parameters:

    hyb – [in] the hybrid matrix structure.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – `hyb` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

### rocsparse_copy_hyb_mat()

rocsparse_status rocsparse_copy_hyb_mat(rocsparse_hyb_mat dest, const rocsparse_hyb_mat src)

  Copy a `HYB` matrix structure.

  `rocsparse_copy_hyb_mat` copies a matrix info structure. Both, source and destination matrix info structure must be initialized prior to calling `rocsparse_copy_hyb_mat`.

  Parameters:

    - dest – [out] the pointer to the destination matrix info structure.

    - src – [in] the pointer to the source matrix info structure.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – `hyb` pointer is invalid.

### rocsparse_create_mat_info()

rocsparse_status rocsparse_create_mat_info(rocsparse_mat_info *info)

  Create a matrix info structure.

  `rocsparse_create_mat_info` creates a structure that holds the matrix info data that is gathered during the analysis routines available. It should be destroyed at the end using rocsparse_destroy_mat_info().

  Parameters:

    info – [inout] the pointer to the info structure.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – `info` pointer is invalid.

### rocsparse_copy_mat_info()

rocsparse_status rocsparse_copy_mat_info(rocsparse_mat_info dest, const rocsparse_mat_info src)

  Copy a matrix info structure.

  `rocsparse_copy_mat_info` copies a matrix info structure. Both, source and destination matrix info structure must be initialized prior to calling `rocsparse_copy_mat_info`.

  Parameters:

    - dest – [out] the pointer to the destination matrix info structure.

    - src – [in] the pointer to the source matrix info structure.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – `src` or `dest` pointer is invalid.

### rocsparse_destroy_mat_info()

rocsparse_status rocsparse_destroy_mat_info(rocsparse_mat_info info)

  Destroy a matrix info structure.

  `rocsparse_destroy_mat_info` destroys a matrix info structure.

  Parameters:

    info – [in] the info structure.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – `info` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

### rocsparse_create_color_info()

rocsparse_status rocsparse_create_color_info(rocsparse_color_info *info)

  Create a color info structure.

  `rocsparse_create_color_info` creates a structure that holds the color info data that is gathered during the analysis routines available. It should be destroyed at the end using rocsparse_destroy_color_info().

  Parameters:

    info – [inout] the pointer to the info structure.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – `info` pointer is invalid.

### rocsparse_destroy_color_info()

rocsparse_status rocsparse_destroy_color_info(rocsparse_color_info info)

  Destroy a color info structure.

  `rocsparse_destroy_color_info` destroys a color info structure.

  Parameters:

    info – [in] the info structure.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – `info` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

### rocsparse_copy_color_info()

rocsparse_status rocsparse_copy_color_info(rocsparse_color_info dest, const rocsparse_color_info src)

  Copy a color info structure.

  `rocsparse_copy_color_info` copies a color info structure. Both, source and destination color info structure must be initialized prior to calling `rocsparse_copy_color_info`.

  Parameters:

    - dest – [out] the pointer to the destination color info structure.

    - src – [in] the pointer to the source color info structure.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – `src` or `dest` pointer is invalid.

### rocsparse_create_spvec_descr()

rocsparse_status rocsparse_create_spvec_descr(rocsparse_spvec_descr *descr, int64_t size, int64_t nnz, void *indices, void *values, rocsparse_indextype idx_type, rocsparse_index_base idx_base, rocsparse_datatype data_type)

  Create a sparse vector descriptor.

  `rocsparse_create_spvec_descr` creates a sparse vector descriptor. It should be destroyed at the end using rocsparse_destroy_mat_descr().

  Parameters:

    - descr – [out] the pointer to the sparse vector descriptor.

    - size – [in] size of the sparse vector.

    - nnz – [in] number of non-zeros in sparse vector.

    - indices – [in] indices of the sparse vector where non-zeros occur (must be array of length `nnz` ).

    - values – [in] non-zero values in the sparse vector (must be array of length `nnz` ).

    - idx_type – [in] rocsparse_indextype_i32 or rocsparse_indextype_i64.

    - idx_base – [in] rocsparse_index_base_zero or rocsparse_index_base_one.

    - data_type – [in] rocsparse_datatype_f32_r, rocsparse_datatype_f64_r, rocsparse_datatype_f32_c or rocsparse_datatype_f64_c.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – if `descr` or `indices` or `values` is invalid.

    - rocsparse_status_invalid_size – if `size` or `nnz` is invalid.

    - rocsparse_status_invalid_value – if `idx_type` or `idx_base` or `data_type` is invalid.

### rocsparse_destroy_spvec_descr()

rocsparse_status rocsparse_destroy_spvec_descr(rocsparse_spvec_descr descr)

  Destroy a sparse vector descriptor.

  `rocsparse_destroy_spvec_descr` destroys a sparse vector descriptor and releases all resources used by the descriptor.

  Parameters:

    descr – [in] the matrix descriptor.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – `descr` is invalid.

### rocsparse_spvec_get()

rocsparse_status rocsparse_spvec_get(const rocsparse_spvec_descr descr, int64_t *size, int64_t *nnz, void **indices, void **values, rocsparse_indextype *idx_type, rocsparse_index_base *idx_base, rocsparse_datatype *data_type)

  Get the fields of the sparse vector descriptor.

  `rocsparse_spvec_get` gets the fields of the sparse vector descriptor

  Parameters:

    - descr – [in] the pointer to the sparse vector descriptor.

    - size – [out] size of the sparse vector.

    - nnz – [out] number of non-zeros in sparse vector.

    - indices – [out] indices of the sparse vector where non-zeros occur (must be array of length `nnz` ).

    - values – [out] non-zero values in the sparse vector (must be array of length `nnz` ).

    - idx_type – [out] rocsparse_indextype_i32 or rocsparse_indextype_i64.

    - idx_base – [out] rocsparse_index_base_zero or rocsparse_index_base_one.

    - data_type – [out] rocsparse_datatype_f32_r, rocsparse_datatype_f64_r, rocsparse_datatype_f32_c or rocsparse_datatype_f64_c.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – if `descr` or `indices` or `values` is invalid.

    - rocsparse_status_invalid_size – if `size` or `nnz` is invalid.

    - rocsparse_status_invalid_value – if `idx_type` or `idx_base` or `data_type` is invalid.

### rocsparse_spvec_get_index_base()

rocsparse_status rocsparse_spvec_get_index_base(const rocsparse_spvec_descr descr, rocsparse_index_base *idx_base)

  Get the index base stored in the sparse vector descriptor.

  Parameters:

    - descr – [in] the pointer to the sparse vector descriptor.

    - idx_base – [out] rocsparse_index_base_zero or rocsparse_index_base_one.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – if `descr` is invalid.

    - rocsparse_status_invalid_value – if `idx_base` is invalid.

### rocsparse_spvec_get_values()

rocsparse_status rocsparse_spvec_get_values(const rocsparse_spvec_descr descr, void **values)

  Get the values array stored in the sparse vector descriptor.

  Parameters:

    - descr – [in] the pointer to the sparse vector descriptor.

    - values – [out] non-zero values in the sparse vector (must be array of length `nnz` ).

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – if `descr` or `values` is invalid.

### rocsparse_spvec_set_values()

rocsparse_status rocsparse_spvec_set_values(rocsparse_spvec_descr descr, void *values)

  Set the values array in the sparse vector descriptor.

  Parameters:

    - descr – [inout] the pointer to the sparse vector descriptor.

    - values – [in] non-zero values in the sparse vector (must be array of length `nnz` ).

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – if `descr` or `values` is invalid.

### rocsparse_create_coo_descr

rocsparse_status rocsparse_create_coo_descr(rocsparse_spmat_descr *descr, int64_t rows, int64_t cols, int64_t nnz, void *coo_row_ind, void *coo_col_ind, void *coo_val, rocsparse_indextype idx_type, rocsparse_index_base idx_base, rocsparse_datatype data_type)

  Create a sparse COO matrix descriptor.

  `rocsparse_create_coo_descr` creates a sparse COO matrix descriptor. It should be destroyed at the end using `rocsparse_destroy_spmat_descr`.

  Parameters:

    - descr – [out] the pointer to the sparse COO matrix descriptor.

    - rows – [in] number of rows in the COO matrix.

    - cols – [in] number of columns in the COO matrix

    - nnz – [in] number of non-zeros in the COO matrix.

    - coo_row_ind – [in] row indices of the COO matrix (must be array of length `nnz` ).

    - coo_col_ind – [in] column indices of the COO matrix (must be array of length `nnz` ).

    - coo_val – [in] values of the COO matrix (must be array of length `nnz` ).

    - idx_type – [in] rocsparse_indextype_i32 or rocsparse_indextype_i64.

    - idx_base – [in] rocsparse_index_base_zero or rocsparse_index_base_one.

    - data_type – [in] rocsparse_datatype_f32_r, rocsparse_datatype_f64_r, rocsparse_datatype_f32_c or rocsparse_datatype_f64_c.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – if `descr` or `coo_row_ind` or `coo_col_ind` or `coo_val` is invalid.

    - rocsparse_status_invalid_size – if `rows` or `cols` or `nnz` is invalid.

    - rocsparse_status_invalid_value – if `idx_type` or `idx_base` or `data_type` is invalid.

### rocsparse_create_coo_aos_descr

rocsparse_status rocsparse_create_coo_aos_descr(rocsparse_spmat_descr *descr, int64_t rows, int64_t cols, int64_t nnz, void *coo_ind, void *coo_val, rocsparse_indextype idx_type, rocsparse_index_base idx_base, rocsparse_datatype data_type)

  Create a sparse COO AoS matrix descriptor.

  `rocsparse_create_coo_aos_descr` creates a sparse COO AoS matrix descriptor. It should be destroyed at the end using `rocsparse_destroy_spmat_descr`.

  Parameters:

    - descr – [out] the pointer to the sparse COO AoS matrix descriptor.

    - rows – [in] number of rows in the COO AoS matrix.

    - cols – [in] number of columns in the COO AoS matrix

    - nnz – [in] number of non-zeros in the COO AoS matrix.

    - coo_ind – [in] <row, column> indices of the COO AoS matrix (must be array of length `nnz` ).

    - coo_val – [in] values of the COO AoS matrix (must be array of length `nnz` ).

    - idx_type – [in] rocsparse_indextype_i32 or rocsparse_indextype_i64.

    - idx_base – [in] rocsparse_index_base_zero or rocsparse_index_base_one.

    - data_type – [in] rocsparse_datatype_f32_r, rocsparse_datatype_f64_r, rocsparse_datatype_f32_c or rocsparse_datatype_f64_c.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – if `descr` or `coo_ind` or `coo_val` is invalid.

    - rocsparse_status_invalid_size – if `rows` or `cols` or `nnz` is invalid.

    - rocsparse_status_invalid_value – if `idx_type` or `idx_base` or `data_type` is invalid.

### rocsparse_create_csr_descr

rocsparse_status rocsparse_create_csr_descr(rocsparse_spmat_descr *descr, int64_t rows, int64_t cols, int64_t nnz, void *csr_row_ptr, void *csr_col_ind, void *csr_val, rocsparse_indextype row_ptr_type, rocsparse_indextype col_ind_type, rocsparse_index_base idx_base, rocsparse_datatype data_type)

  Create a sparse CSR matrix descriptor.

  `rocsparse_create_csr_descr` creates a sparse CSR matrix descriptor. It should be destroyed at the end using `rocsparse_destroy_spmat_descr`.

  Parameters:

    - descr – [out] the pointer to the sparse CSR matrix descriptor.

    - rows – [in] number of rows in the CSR matrix.

    - cols – [in] number of columns in the CSR matrix

    - nnz – [in] number of non-zeros in the CSR matrix.

    - csr_row_ptr – [in] row offsets of the CSR matrix (must be array of length `rows+1` ).

    - csr_col_ind – [in] column indices of the CSR matrix (must be array of length `nnz` ).

    - csr_val – [in] values of the CSR matrix (must be array of length `nnz` ).

    - row_ptr_type – [in] rocsparse_indextype_i32 or rocsparse_indextype_i64.

    - col_ind_type – [in] rocsparse_indextype_i32 or rocsparse_indextype_i64.

    - idx_base – [in] rocsparse_index_base_zero or rocsparse_index_base_one.

    - data_type – [in] rocsparse_datatype_f32_r, rocsparse_datatype_f64_r, rocsparse_datatype_f32_c or rocsparse_datatype_f64_c.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – if `descr` or `csr_row_ptr` or `csr_col_ind` or `csr_val` is invalid.

    - rocsparse_status_invalid_size – if `rows` or `cols` or `nnz` is invalid.

    - rocsparse_status_invalid_value – if `row_ptr_type` or `col_ind_type` or `idx_base` or `data_type` is invalid.

### rocsparse_create_csc_descr

rocsparse_status rocsparse_create_csc_descr(rocsparse_spmat_descr *descr, int64_t rows, int64_t cols, int64_t nnz, void *csc_col_ptr, void *csc_row_ind, void *csc_val, rocsparse_indextype col_ptr_type, rocsparse_indextype row_ind_type, rocsparse_index_base idx_base, rocsparse_datatype data_type)

  Create a sparse CSC matrix descriptor.

  `rocsparse_create_csc_descr` creates a sparse CSC matrix descriptor. It should be destroyed at the end using `rocsparse_destroy_spmat_descr`.

  Parameters:

    - descr – [out] the pointer to the sparse CSC matrix descriptor.

    - rows – [in] number of rows in the CSC matrix.

    - cols – [in] number of columns in the CSC matrix

    - nnz – [in] number of non-zeros in the CSC matrix.

    - csc_col_ptr – [in] column offsets of the CSC matrix (must be array of length `cols+1` ).

    - csc_row_ind – [in] row indices of the CSC matrix (must be array of length `nnz` ).

    - csc_val – [in] values of the CSC matrix (must be array of length `nnz` ).

    - col_ptr_type – [in] rocsparse_indextype_i32 or rocsparse_indextype_i64.

    - row_ind_type – [in] rocsparse_indextype_i32 or rocsparse_indextype_i64.

    - idx_base – [in] rocsparse_index_base_zero or rocsparse_index_base_one.

    - data_type – [in] rocsparse_datatype_f32_r, rocsparse_datatype_f64_r, rocsparse_datatype_f32_c or rocsparse_datatype_f64_c.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – if `descr` or `csc_col_ptr` or `csc_row_ind` or `csc_val` is invalid.

    - rocsparse_status_invalid_size – if `rows` or `cols` or `nnz` is invalid.

    - rocsparse_status_invalid_value – if `col_ptr_type` or `row_ind_type` or `idx_base` or `data_type` is invalid.

### rocsparse_create_ell_descr

rocsparse_status rocsparse_create_ell_descr(rocsparse_spmat_descr *descr, int64_t rows, int64_t cols, void *ell_col_ind, void *ell_val, int64_t ell_width, rocsparse_indextype idx_type, rocsparse_index_base idx_base, rocsparse_datatype data_type)

  Create a sparse ELL matrix descriptor.

  `rocsparse_create_ell_descr` creates a sparse ELL matrix descriptor. It should be destroyed at the end using `rocsparse_destroy_spmat_descr`.

  Parameters:

    - descr – [out] the pointer to the sparse ELL matrix descriptor.

    - rows – [in] number of rows in the ELL matrix.

    - cols – [in] number of columns in the ELL matrix

    - ell_col_ind – [in] column indices of the ELL matrix (must be array of length `rows*ell_width` ).

    - ell_val – [in] values of the ELL matrix (must be array of length `rows*ell_width` ).

    - ell_width – [in] width of the ELL matrix.

    - idx_type – [in] rocsparse_indextype_i32 or rocsparse_indextype_i64.

    - idx_base – [in] rocsparse_index_base_zero or rocsparse_index_base_one.

    - data_type – [in] rocsparse_datatype_f32_r, rocsparse_datatype_f64_r, rocsparse_datatype_f32_c or rocsparse_datatype_f64_c.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – if `descr` or `ell_col_ind` or `ell_val` is invalid.

    - rocsparse_status_invalid_size – if `rows` or `cols` or `ell_width` is invalid.

    - rocsparse_status_invalid_value – if `idx_type` or `idx_base` or `data_type` is invalid.

### rocsparse_create_bell_descr

rocsparse_status rocsparse_create_bell_descr(rocsparse_spmat_descr *descr, int64_t rows, int64_t cols, rocsparse_direction ell_block_dir, int64_t ell_block_dim, int64_t ell_cols, void *ell_col_ind, void *ell_val, rocsparse_indextype idx_type, rocsparse_index_base idx_base, rocsparse_datatype data_type)

  Create a sparse blocked ELL matrix descriptor.

  `rocsparse_create_bell_descr` creates a sparse blocked ELL matrix descriptor. It should be destroyed at the end using `rocsparse_destroy_spmat_descr`.

  Parameters:

    - descr – [out] the pointer to the sparse blocked ELL matrix descriptor.

    - rows – [in] number of rows in the blocked ELL matrix.

    - cols – [in] number of columns in the blocked ELL matrix

    - ell_block_dir – [in] rocsparse_direction_row or rocsparse_direction_column.

    - ell_block_dim – [in] block dimension of the sparse blocked ELL matrix.

    - ell_cols – [in] column indices of the blocked ELL matrix (must be array of length `rows*ell_width` ).

    - ell_col_ind – [in] column indices of the blocked ELL matrix (must be array of length `rows*ell_width` ).

    - ell_val – [in] values of the blocked ELL matrix (must be array of length `rows*ell_width` ).

    - idx_type – [in] rocsparse_indextype_i32 or rocsparse_indextype_i64.

    - idx_base – [in] rocsparse_index_base_zero or rocsparse_index_base_one.

    - data_type – [in] rocsparse_datatype_f32_r, rocsparse_datatype_f64_r, rocsparse_datatype_f32_c or rocsparse_datatype_f64_c.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – if `descr` or `ell_cols` or `ell_col_ind` or `ell_val` is invalid.

    - rocsparse_status_invalid_size – if `rows` or `cols` is invalid.

    - rocsparse_status_invalid_value – if `idx_type` or `idx_base` or `data_type` is invalid.

### rocsparse_destroy_spmat_descr

rocsparse_status rocsparse_destroy_spmat_descr(rocsparse_spmat_descr descr)

  Destroy a sparse matrix descriptor.

  `rocsparse_destroy_spmat_descr` destroys a sparse matrix descriptor and releases all resources used by the descriptor.

  Parameters:

    descr – [in] the matrix descriptor.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – `descr` is invalid.

### rocsparse_coo_get

rocsparse_status rocsparse_coo_get(const rocsparse_spmat_descr descr, int64_t *rows, int64_t *cols, int64_t *nnz, void **coo_row_ind, void **coo_col_ind, void **coo_val, rocsparse_indextype *idx_type, rocsparse_index_base *idx_base, rocsparse_datatype *data_type)

  Get the fields of the sparse COO matrix descriptor.

  `rocsparse_coo_get` gets the fields of the sparse COO matrix descriptor

  Parameters:

    - descr – [in] the pointer to the sparse COO matrix descriptor.

    - rows – [out] number of rows in the sparse COO matrix.

    - cols – [out] number of columns in the sparse COO matrix.

    - nnz – [out] number of non-zeros in sparse COO matrix.

    - coo_row_ind – [out] row indices of the COO matrix (must be array of length `nnz` ).

    - coo_col_ind – [out] column indices of the COO matrix (must be array of length `nnz` ).

    - coo_val – [out] values of the COO matrix (must be array of length `nnz` ).

    - idx_type – [out] rocsparse_indextype_i32 or rocsparse_indextype_i64.

    - idx_base – [out] rocsparse_index_base_zero or rocsparse_index_base_one.

    - data_type – [out] rocsparse_datatype_f32_r, rocsparse_datatype_f64_r, rocsparse_datatype_f32_c or rocsparse_datatype_f64_c.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – if `descr` or `coo_row_ind` or `coo_col_ind` or `coo_val` is invalid.

    - rocsparse_status_invalid_size – if `rows` or `cols` or `nnz` is invalid.

    - rocsparse_status_invalid_value – if `idx_type` or `idx_base` or `data_type` is invalid.

### rocsparse_coo_aos_get

rocsparse_status rocsparse_coo_aos_get(const rocsparse_spmat_descr descr, int64_t *rows, int64_t *cols, int64_t *nnz, void **coo_ind, void **coo_val, rocsparse_indextype *idx_type, rocsparse_index_base *idx_base, rocsparse_datatype *data_type)

  Get the fields of the sparse COO AoS matrix descriptor.

  `rocsparse_coo_aos_get` gets the fields of the sparse COO AoS matrix descriptor

  Parameters:

    - descr – [in] the pointer to the sparse COO AoS matrix descriptor.

    - rows – [out] number of rows in the sparse COO AoS matrix.

    - cols – [out] number of columns in the sparse COO AoS matrix.

    - nnz – [out] number of non-zeros in sparse COO AoS matrix.

    - coo_ind – [out] <row, columns> indices of the COO AoS matrix (must be array of length `nnz` ).

    - coo_val – [out] values of the COO AoS matrix (must be array of length `nnz` ).

    - idx_type – [out] rocsparse_indextype_i32 or rocsparse_indextype_i64.

    - idx_base – [out] rocsparse_index_base_zero or rocsparse_index_base_one.

    - data_type – [out] rocsparse_datatype_f32_r, rocsparse_datatype_f64_r, rocsparse_datatype_f32_c or rocsparse_datatype_f64_c.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – if `descr` or `coo_ind` or `coo_val` is invalid.

    - rocsparse_status_invalid_size – if `rows` or `cols` or `nnz` is invalid.

    - rocsparse_status_invalid_value – if `idx_type` or `idx_base` or `data_type` is invalid.

### rocsparse_csr_get

rocsparse_status rocsparse_csr_get(const rocsparse_spmat_descr descr, int64_t *rows, int64_t *cols, int64_t *nnz, void **csr_row_ptr, void **csr_col_ind, void **csr_val, rocsparse_indextype *row_ptr_type, rocsparse_indextype *col_ind_type, rocsparse_index_base *idx_base, rocsparse_datatype *data_type)

  Get the fields of the sparse CSR matrix descriptor.

  `rocsparse_csr_get` gets the fields of the sparse CSR matrix descriptor

  Parameters:

    - descr – [in] the pointer to the sparse CSR matrix descriptor.

    - rows – [out] number of rows in the CSR matrix.

    - cols – [out] number of columns in the CSR matrix

    - nnz – [out] number of non-zeros in the CSR matrix.

    - csr_row_ptr – [out] row offsets of the CSR matrix (must be array of length `rows+1` ).

    - csr_col_ind – [out] column indices of the CSR matrix (must be array of length `nnz` ).

    - csr_val – [out] values of the CSR matrix (must be array of length `nnz` ).

    - row_ptr_type – [out] rocsparse_indextype_i32 or rocsparse_indextype_i64.

    - col_ind_type – [out] rocsparse_indextype_i32 or rocsparse_indextype_i64.

    - idx_base – [out] rocsparse_index_base_zero or rocsparse_index_base_one.

    - data_type – [out] rocsparse_datatype_f32_r, rocsparse_datatype_f64_r, rocsparse_datatype_f32_c or rocsparse_datatype_f64_c.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – if `descr` or `csr_row_ptr` or `csr_col_ind` or `csr_val` is invalid.

    - rocsparse_status_invalid_size – if `rows` or `cols` or `nnz` is invalid.

    - rocsparse_status_invalid_value – if `row_ptr_type` or `col_ind_type` or `idx_base` or `data_type` is invalid.

### rocsparse_ell_get

rocsparse_status rocsparse_ell_get(const rocsparse_spmat_descr descr, int64_t *rows, int64_t *cols, void **ell_col_ind, void **ell_val, int64_t *ell_width, rocsparse_indextype *idx_type, rocsparse_index_base *idx_base, rocsparse_datatype *data_type)

  Get the fields of the sparse ELL matrix descriptor.

  `rocsparse_ell_get` gets the fields of the sparse ELL matrix descriptor

  Parameters:

    - descr – [in] the pointer to the sparse ELL matrix descriptor.

    - rows – [out] number of rows in the ELL matrix.

    - cols – [out] number of columns in the ELL matrix

    - ell_col_ind – [out] column indices of the ELL matrix (must be array of length `rows*ell_width` ).

    - ell_val – [out] values of the ELL matrix (must be array of length `rows*ell_width` ).

    - ell_width – [out] width of the ELL matrix.

    - idx_type – [out] rocsparse_indextype_i32 or rocsparse_indextype_i64.

    - idx_base – [out] rocsparse_index_base_zero or rocsparse_index_base_one.

    - data_type – [out] rocsparse_datatype_f32_r, rocsparse_datatype_f64_r, rocsparse_datatype_f32_c or rocsparse_datatype_f64_c.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – if `descr` or `ell_col_ind` or `ell_val` is invalid.

    - rocsparse_status_invalid_size – if `rows` or `cols` or `ell_width` is invalid.

    - rocsparse_status_invalid_value – if `idx_type` or `idx_base` or `data_type` is invalid.

### rocsparse_bell_get

rocsparse_status rocsparse_bell_get(const rocsparse_spmat_descr descr, int64_t *rows, int64_t *cols, rocsparse_direction *ell_block_dir, int64_t *ell_block_dim, int64_t *ell_cols, void **ell_col_ind, void **ell_val, rocsparse_indextype *idx_type, rocsparse_index_base *idx_base, rocsparse_datatype *data_type)

  Get the fields of the sparse blocked ELL matrix descriptor.

  `rocsparse_bell_get` gets the fields of the sparse blocked ELL matrix descriptor

  Parameters:

    - descr – [in] the pointer to the sparse blocked ELL matrix descriptor.

    - rows – [out] number of rows in the blocked ELL matrix.

    - cols – [out] number of columns in the blocked ELL matrix

    - ell_block_dir – [out] rocsparse_direction_row or rocsparse_direction_column.

    - ell_block_dim – [out] block dimension of the sparse blocked ELL matrix.

    - ell_cols – [out] column indices of the blocked ELL matrix (must be array of length `rows*ell_width` ).

    - ell_col_ind – [out] column indices of the blocked ELL matrix (must be array of length `rows*ell_width` ).

    - ell_val – [out] values of the blocked ELL matrix (must be array of length `rows*ell_width` ).

    - idx_type – [out] rocsparse_indextype_i32 or rocsparse_indextype_i64.

    - idx_base – [out] rocsparse_index_base_zero or rocsparse_index_base_one.

    - data_type – [out] rocsparse_datatype_f32_r, rocsparse_datatype_f64_r, rocsparse_datatype_f32_c or rocsparse_datatype_f64_c.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – if `descr` or `ell_cols` or `ell_col_ind` or `ell_val` is invalid.

    - rocsparse_status_invalid_size – if `rows` or `cols` or `ell_block_dim` is invalid.

    - rocsparse_status_invalid_value – if `ell_block_dir` or `idx_type` or `idx_base` or `data_type` is invalid.

### rocsparse_coo_set_pointers

rocsparse_status rocsparse_coo_set_pointers(rocsparse_spmat_descr descr, void *coo_row_ind, void *coo_col_ind, void *coo_val)

  Set the row indices, column indices and values array in the sparse COO matrix descriptor.

  Parameters:

    - descr – [inout] the pointer to the sparse vector descriptor.

    - coo_row_ind – [in] row indices of the COO matrix (must be array of length `nnz` ).

    - coo_col_ind – [in] column indices of the COO matrix (must be array of length `nnz` ).

    - coo_val – [in] values of the COO matrix (must be array of length `nnz` ).

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – if `descr` or `coo_row_ind` or `coo_col_ind` or `coo_val` is invalid.

### rocsparse_coo_aos_set_pointers

rocsparse_status rocsparse_coo_aos_set_pointers(rocsparse_spmat_descr descr, void *coo_ind, void *coo_val)

  Set the <row, column> indices and values array in the sparse COO AoS matrix descriptor.

  Parameters:

    - descr – [inout] the pointer to the sparse vector descriptor.

    - coo_ind – [in] <row, column> indices of the COO matrix (must be array of length `nnz` ).

    - coo_val – [in] values of the COO matrix (must be array of length `nnz` ).

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – if `descr` or `coo_ind` or `coo_val` is invalid.

### rocsparse_csr_set_pointers

rocsparse_status rocsparse_csr_set_pointers(rocsparse_spmat_descr descr, void *csr_row_ptr, void *csr_col_ind, void *csr_val)

  Set the row offsets, column indices and values array in the sparse CSR matrix descriptor.

  Parameters:

    - descr – [inout] the pointer to the sparse vector descriptor.

    - csr_row_ptr – [in] row offsets of the CSR matrix (must be array of length `rows+1` ).

    - csr_col_ind – [in] column indices of the CSR matrix (must be array of length `nnz` ).

    - csr_val – [in] values of the CSR matrix (must be array of length `nnz` ).

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – if `descr` or `coo_ind` or `coo_val` is invalid.

### rocsparse_csc_set_pointers

rocsparse_status rocsparse_csc_set_pointers(rocsparse_spmat_descr descr, void *csc_col_ptr, void *csc_row_ind, void *csc_val)

  Set the column offsets, row indices and values array in the sparse CSC matrix descriptor.

  Parameters:

    - descr – [inout] the pointer to the sparse vector descriptor.

    - csc_col_ptr – [in] column offsets of the CSC matrix (must be array of length `cols+1` ).

    - csc_row_ind – [in] row indices of the CSC matrix (must be array of length `nnz` ).

    - csc_val – [in] values of the CSC matrix (must be array of length `nnz` ).

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – if `descr` or `csc_col_ptr` or `csc_row_ind` or `csc_val` is invalid.

### rocsparse_ell_set_pointers

rocsparse_status rocsparse_ell_set_pointers(rocsparse_spmat_descr descr, void *ell_col_ind, void *ell_val)

  Set the column indices and values array in the sparse ELL matrix descriptor.

  Parameters:

    - descr – [inout] the pointer to the sparse vector descriptor.

    - ell_col_ind – [in] column indices of the ELL matrix (must be array of length `rows*ell_width` ).

    - ell_val – [in] values of the ELL matrix (must be array of length `rows*ell_width` ).

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – if `descr` or `ell_col_ind` or `ell_val` is invalid.

### rocsparse_bsr_set_pointers

rocsparse_status rocsparse_bsr_set_pointers(rocsparse_spmat_descr descr, void *bsr_row_ptr, void *bsr_col_ind, void *bsr_val)

  Set the row offsets, column indices and values array in the sparse BSR matrix descriptor.

  Parameters:

    - descr – [inout] the pointer to the sparse vector descriptor.

    - bsr_row_ptr – [in] row offsets of the BSR matrix (must be array of length `rows+1` ).

    - bsr_col_ind – [in] column indices of the BSR matrix (must be array of length `nnzb` ).

    - bsr_val – [in] values of the BSR matrix (must be array of length `nnzb*block_dim*block_dim` ).

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – if `descr` or `bsr_row_ptr` or `bsr_col_ind` or `bsr_val` is invalid.

### rocsparse_spmat_get_size

rocsparse_status rocsparse_spmat_get_size(rocsparse_spmat_descr descr, int64_t *rows, int64_t *cols, int64_t *nnz)

  Get the number of rows, columns and non-zeros from the sparse matrix descriptor.

  Parameters:

    - descr – [in] the pointer to the sparse matrix descriptor.

    - rows – [out] number of rows in the sparse matrix.

    - cols – [out] number of columns in the sparse matrix.

    - nnz – [out] number of non-zeros in sparse matrix.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – if `descr` is invalid.

    - rocsparse_status_invalid_size – if `rows` or `cols` or `nnz` is invalid.

### rocsparse_spmat_get_format

rocsparse_status rocsparse_spmat_get_format(const rocsparse_spmat_descr descr, rocsparse_format *format)

  Get the sparse matrix format from the sparse matrix descriptor.

  Parameters:

    - descr – [in] the pointer to the sparse matrix descriptor.

    - format – [out] rocsparse_format_coo or rocsparse_format_coo_aos or rocsparse_format_csr or rocsparse_format_csc or rocsparse_format_ell

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – if `descr` is invalid.

    - rocsparse_status_invalid_value – if `format` is invalid.

### rocsparse_spmat_get_index_base

rocsparse_status rocsparse_spmat_get_index_base(const rocsparse_spmat_descr descr, rocsparse_index_base *idx_base)

  Get the sparse matrix index base from the sparse matrix descriptor.

  Parameters:

    - descr – [in] the pointer to the sparse matrix descriptor.

    - idx_base – [out] rocsparse_index_base_zero or rocsparse_index_base_one

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – if `descr` is invalid.

    - rocsparse_status_invalid_value – if `idx_base` is invalid.

### rocsparse_spmat_get_values

rocsparse_status rocsparse_spmat_get_values(rocsparse_spmat_descr descr, void **values)

  Get the values array from the sparse matrix descriptor.

  Parameters:

    - descr – [in] the pointer to the sparse matrix descriptor.

    - values – [out] values array of the sparse matrix.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – if `descr` or `values` is invalid.

### rocsparse_spmat_set_values

rocsparse_status rocsparse_spmat_set_values(rocsparse_spmat_descr descr, void *values)

  Set the values array in the sparse matrix descriptor.

  Parameters:

    - descr – [inout] the pointer to the sparse matrix descriptor.

    - values – [in] values array of the sparse matrix.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – if `descr` or `values` is invalid.

### rocsparse_spmat_get_strided_batch

rocsparse_status rocsparse_spmat_get_strided_batch(rocsparse_spmat_descr descr, int *batch_count)

  Get the strided batch count from the sparse matrix descriptor.

  Parameters:

    - descr – [in] the pointer to the sparse matrix descriptor.

    - batch_count – [out] batch_count of the sparse matrix.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – if `descr` is invalid.

    - rocsparse_status_invalid_size – if `batch_count` is invalid.

### rocsparse_spmat_set_strided_batch

rocsparse_status rocsparse_spmat_set_strided_batch(rocsparse_spmat_descr descr, int batch_count)

  Set the strided batch count in the sparse matrix descriptor.

  Parameters:

    - descr – [in] the pointer to the sparse matrix descriptor.

    - batch_count – [in] batch_count of the sparse matrix.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – if `descr` is invalid.

    - rocsparse_status_invalid_size – if `batch_count` is invalid.

### rocsparse_coo_set_strided_batch

rocsparse_status rocsparse_coo_set_strided_batch(rocsparse_spmat_descr descr, int batch_count, int64_t batch_stride)

  Set the batch count and batch stride in the sparse COO matrix descriptor.

  Parameters:

    - descr – [inout] the pointer to the sparse COO matrix descriptor.

    - batch_count – [in] batch_count of the sparse COO matrix.

    - batch_stride – [in] batch stride of the sparse COO matrix.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – if `descr` is invalid.

    - rocsparse_status_invalid_size – if `batch_count` or `batch_stride` is invalid.

### rocsparse_csr_set_strided_batch

rocsparse_status rocsparse_csr_set_strided_batch(rocsparse_spmat_descr descr, int batch_count, int64_t offsets_batch_stride, int64_t columns_values_batch_stride)

  Set the batch count, row offset batch stride and the column indices batch stride in the sparse CSR matrix descriptor.

  Parameters:

    - descr – [inout] the pointer to the sparse CSR matrix descriptor.

    - batch_count – [in] batch_count of the sparse CSR matrix.

    - offsets_batch_stride – [in] row offset batch stride of the sparse CSR matrix.

    - columns_values_batch_stride – [in] column indices batch stride of the sparse CSR matrix.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – if `descr` is invalid.

    - rocsparse_status_invalid_size – if `batch_count` or `offsets_batch_stride` or `columns_values_batch_stride` is invalid.

### rocsparse_csc_set_strided_batch

rocsparse_status rocsparse_csc_set_strided_batch(rocsparse_spmat_descr descr, int batch_count, int64_t offsets_batch_stride, int64_t rows_values_batch_stride)

  Set the batch count, column offset batch stride and the row indices batch stride in the sparse CSC matrix descriptor.

  Parameters:

    - descr – [inout] the pointer to the sparse CSC matrix descriptor.

    - batch_count – [in] batch_count of the sparse CSC matrix.

    - offsets_batch_stride – [in] column offset batch stride of the sparse CSC matrix.

    - rows_values_batch_stride – [in] row indices batch stride of the sparse CSC matrix.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – if `descr` is invalid.

    - rocsparse_status_invalid_size – if `batch_count` or `offsets_batch_stride` or `rows_values_batch_stride` is invalid.

### rocsparse_spmat_get_attribute

rocsparse_status rocsparse_spmat_get_attribute(rocsparse_spmat_descr descr, rocsparse_spmat_attribute attribute, void *data, size_t data_size)

  Get the requested attribute data from the sparse matrix descriptor.

  Parameters:

    - descr – [in] the pointer to the sparse matrix descriptor.

    - attribute – [in] rocsparse_spmat_fill_mode or rocsparse_spmat_diag_type or rocsparse_spmat_matrix_type or rocsparse_spmat_storage_mode

    - data – [out] attribute data

    - data_size – [in] attribute data size.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – if `descr` or `data` is invalid.

    - rocsparse_status_invalid_value – if `attribute` is invalid.

    - rocsparse_status_invalid_size – if `data_size` is invalid.

### rocsparse_spmat_set_attribute

rocsparse_status rocsparse_spmat_set_attribute(rocsparse_spmat_descr descr, rocsparse_spmat_attribute attribute, const void *data, size_t data_size)

  Set the requested attribute data in the sparse matrix descriptor.

  Parameters:

    - descr – [inout] the pointer to the sparse matrix descriptor.

    - attribute – [in] rocsparse_spmat_fill_mode or rocsparse_spmat_diag_type or rocsparse_spmat_matrix_type or rocsparse_spmat_storage_mode

    - data – [in] attribute data

    - data_size – [in] attribute data size.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – if `descr` or `data` is invalid.

    - rocsparse_status_invalid_value – if `attribute` is invalid.

    - rocsparse_status_invalid_size – if `data_size` is invalid.

### rocsparse_create_dnvec_descr

rocsparse_status rocsparse_create_dnvec_descr(rocsparse_dnvec_descr *descr, int64_t size, void *values, rocsparse_datatype data_type)

  Create a dense vector descriptor.

  `rocsparse_create_dnvec_descr` creates a dense vector descriptor. It should be destroyed at the end using rocsparse_destroy_dnvec_descr().

  Parameters:

    - descr – [out] the pointer to the dense vector descriptor.

    - size – [in] size of the dense vector.

    - values – [in] non-zero values in the dense vector (must be array of length `size` ).

    - data_type – [in] rocsparse_datatype_f32_r, rocsparse_datatype_f64_r, rocsparse_datatype_f32_c or rocsparse_datatype_f64_c.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – if `descr` or `values` is invalid.

    - rocsparse_status_invalid_size – if `size` is invalid.

    - rocsparse_status_invalid_value – if `data_type` is invalid.

### rocsparse_destroy_dnvec_descr

rocsparse_status rocsparse_destroy_dnvec_descr(rocsparse_dnvec_descr descr)

  Destroy a dense vector descriptor.

  `rocsparse_destroy_dnvec_descr` destroys a dense vector descriptor and releases all resources used by the descriptor.

  Parameters:

    descr – [in] the matrix descriptor.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – `descr` is invalid.

### rocsparse_dnvec_get

rocsparse_status rocsparse_dnvec_get(const rocsparse_dnvec_descr descr, int64_t *size, void **values, rocsparse_datatype *data_type)

  Get the fields of the dense vector descriptor.

  `rocsparse_dnvec_get` gets the fields of the dense vector descriptor

  Parameters:

    - descr – [in] the pointer to the dense vector descriptor.

    - size – [out] size of the dense vector.

    - values – [out] non-zero values in the dense vector (must be array of length `size` ).

    - data_type – [out] rocsparse_datatype_f32_r, rocsparse_datatype_f64_r, rocsparse_datatype_f32_c or rocsparse_datatype_f64_c.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – if `descr` or `values` is invalid.

    - rocsparse_status_invalid_size – if `size` is invalid.

    - rocsparse_status_invalid_value – if `data_type` is invalid.

### rocsparse_dnvec_get_values

rocsparse_status rocsparse_dnvec_get_values(const rocsparse_dnvec_descr descr, void **values)

  Get the values array from a dense vector descriptor.

  Parameters:

    - descr – [in] the matrix descriptor.

    - values – [out] non-zero values in the dense vector (must be array of length `size` ).

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – `descr` or `values` is invalid.

### rocsparse_dnvec_set_values

rocsparse_status rocsparse_dnvec_set_values(rocsparse_dnvec_descr descr, void *values)

  Set the values array in a dense vector descriptor.

  Parameters:

    - descr – [inout] the matrix descriptor.

    - values – [in] non-zero values in the dense vector (must be array of length `size` ).

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – `descr` or `values` is invalid.

### rocsparse_create_dnmat_descr

rocsparse_status rocsparse_create_dnmat_descr(rocsparse_dnmat_descr *descr, int64_t rows, int64_t cols, int64_t ld, void *values, rocsparse_datatype data_type, rocsparse_order order)

  Create a dense matrix descriptor.

  `rocsparse_create_dnmat_descr` creates a dense matrix descriptor. It should be destroyed at the end using rocsparse_destroy_dnmat_descr().

  Parameters:

    - descr – [out] the pointer to the dense matrix descriptor.

    - rows – [in] number of rows in the dense matrix.

    - cols – [in] number of columns in the dense matrix.

    - ld – [in] leading dimension of the dense matrix.

    - values – [in] non-zero values in the dense vector (must be array of length `ld*rows` if `order=rocsparse_order_column` or `ld*cols` if `order=rocsparse_order_row` ).

    - data_type – [in] rocsparse_datatype_f32_r, rocsparse_datatype_f64_r, rocsparse_datatype_f32_c or rocsparse_datatype_f64_c.

    - order – [in] rocsparse_order_row or rocsparse_order_column.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – if `descr` or `values` is invalid.

    - rocsparse_status_invalid_size – if `rows` or `cols` or `ld` is invalid.

    - rocsparse_status_invalid_value – if `data_type` or `order` is invalid.

### rocsparse_destroy_dnmat_descr

rocsparse_status rocsparse_destroy_dnmat_descr(rocsparse_dnmat_descr descr)

  Destroy a dense matrix descriptor.

  `rocsparse_destroy_dnmat_descr` destroys a dense matrix descriptor and releases all resources used by the descriptor.

  Parameters:

    descr – [in] the matrix descriptor.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – `descr` is invalid.

### rocsparse_dnmat_get

rocsparse_status rocsparse_dnmat_get(const rocsparse_dnmat_descr descr, int64_t *rows, int64_t *cols, int64_t *ld, void **values, rocsparse_datatype *data_type, rocsparse_order *order)

  Get the fields of the dense matrix descriptor.

  Parameters:

    - descr – [in] the pointer to the dense matrix descriptor.

    - rows – [out] number of rows in the dense matrix.

    - cols – [out] number of columns in the dense matrix.

    - ld – [out] leading dimension of the dense matrix.

    - values – [out] non-zero values in the dense matrix (must be array of length `ld*rows` if `order=rocsparse_order_column` or `ld*cols` if `order=rocsparse_order_row` ).

    - data_type – [out] rocsparse_datatype_f32_r, rocsparse_datatype_f64_r, rocsparse_datatype_f32_c or rocsparse_datatype_f64_c.

    - order – [out] rocsparse_order_row or rocsparse_order_column.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – if `descr` or `values` is invalid.

    - rocsparse_status_invalid_size – if `rows` or `cols` or `ld` is invalid.

    - rocsparse_status_invalid_value – if `data_type` or `order` is invalid.

### rocsparse_dnmat_get_values

rocsparse_status rocsparse_dnmat_get_values(const rocsparse_dnmat_descr descr, void **values)

  Get the values array from the dense matrix descriptor.

  Parameters:

    - descr – [in] the pointer to the dense matrix descriptor.

    - values – [out] non-zero values in the dense matrix (must be array of length `ld*rows` if `order=rocsparse_order_column` or `ld*cols` if `order=rocsparse_order_row` ).

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – if `descr` or `values` is invalid.

### rocsparse_dnmat_set_values

rocsparse_status rocsparse_dnmat_set_values(rocsparse_dnmat_descr descr, void *values)

  Set the values array in a dense matrix descriptor.

  Parameters:

    - descr – [inout] the matrix descriptor.

    - values – [in] non-zero values in the dense matrix (must be array of length `ld*rows` if `order=rocsparse_order_column` or `ld*cols` if `order=rocsparse_order_row` ).

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – `descr` or `values` is invalid.

### rocsparse_dnmat_get_strided_batch

rocsparse_status rocsparse_dnmat_get_strided_batch(rocsparse_dnmat_descr descr, int *batch_count, int64_t *batch_stride)

  Get the batch count and batch stride from the dense matrix descriptor.

  Parameters:

    - descr – [in] the pointer to the dense matrix descriptor.

    - batch_count – [out] the batch count in the dense matrix.

    - batch_stride – [out] the batch stride in the dense matrix.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – if `descr` is invalid.

    - rocsparse_status_invalid_size – if `batch_count` or `batch_stride` is invalid.

### rocsparse_dnmat_set_strided_batch

rocsparse_status rocsparse_dnmat_set_strided_batch(rocsparse_dnmat_descr descr, int batch_count, int64_t batch_stride)

  Set the batch count and batch stride in the dense matrix descriptor.

  Parameters:

    - descr – [inout] the pointer to the dense matrix descriptor.

    - batch_count – [in] the batch count in the dense matrix.

    - batch_stride – [in] the batch stride in the dense matrix.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_pointer – if `descr` is invalid.

    - rocsparse_status_invalid_size – if `batch_count` or `batch_stride` is invalid.

## Sparse Level 1 Functions

The sparse level 1 routines describe operations between a vector in sparse format and a vector in dense format. This section describes all rocSPARSE level 1 sparse linear algebra functions.

### rocsparse_axpyi()

rocsparse_status rocsparse_saxpyi(rocsparse_handle handle, rocsparse_int nnz, const float *alpha, const float *x_val, const rocsparse_int *x_ind, float *y, rocsparse_index_base idx_base)

rocsparse_status rocsparse_daxpyi(rocsparse_handle handle, rocsparse_int nnz, const double *alpha, const double *x_val, const rocsparse_int *x_ind, double *y, rocsparse_index_base idx_base)

rocsparse_status rocsparse_caxpyi(rocsparse_handle handle, rocsparse_int nnz, const rocsparse_float_complex *alpha, const rocsparse_float_complex *x_val, const rocsparse_int *x_ind, rocsparse_float_complex *y, rocsparse_index_base idx_base)

rocsparse_status rocsparse_zaxpyi(rocsparse_handle handle, rocsparse_int nnz, const rocsparse_double_complex *alpha, const rocsparse_double_complex *x_val, const rocsparse_int *x_ind, rocsparse_double_complex *y, rocsparse_index_base idx_base)

  Scale a sparse vector and add it to a dense vector.

  `rocsparse_axpyi` multiplies the sparse vector \(x\) with scalar \(\alpha\) and adds the result to the dense vector \(y\), such that

  \[ y := y + \alpha \cdot x \]

      for(i = 0; i < nnz; ++i)
      {
          y[x_ind[i]] = y[x_ind[i]] + alpha * x_val[i];
      }

  Note

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

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - nnz – [in] number of non-zero entries of vector \(x\).

    - alpha – [in] scalar \(\alpha\).

    - x_val – [in] array of `nnz` elements containing the values of \(x\).

    - x_ind – [in] array of `nnz` elements containing the indices of the non-zero values of \(x\).

    - y – [inout] array of values in dense format.

    - idx_base – [in] rocsparse_index_base_zero or rocsparse_index_base_one.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_value – `idx_base` is invalid.

    - rocsparse_status_invalid_size – `nnz` is invalid.

    - rocsparse_status_invalid_pointer – `alpha`, `x_val`, `x_ind` or `y` pointer is invalid.

### rocsparse_doti()

rocsparse_status rocsparse_sdoti(rocsparse_handle handle, rocsparse_int nnz, const float *x_val, const rocsparse_int *x_ind, const float *y, float *result, rocsparse_index_base idx_base)

rocsparse_status rocsparse_ddoti(rocsparse_handle handle, rocsparse_int nnz, const double *x_val, const rocsparse_int *x_ind, const double *y, double *result, rocsparse_index_base idx_base)

rocsparse_status rocsparse_cdoti(rocsparse_handle handle, rocsparse_int nnz, const rocsparse_float_complex *x_val, const rocsparse_int *x_ind, const rocsparse_float_complex *y, rocsparse_float_complex *result, rocsparse_index_base idx_base)

rocsparse_status rocsparse_zdoti(rocsparse_handle handle, rocsparse_int nnz, const rocsparse_double_complex *x_val, const rocsparse_int *x_ind, const rocsparse_double_complex *y, rocsparse_double_complex *result, rocsparse_index_base idx_base)

  Compute the dot product of a sparse vector with a dense vector.

  `rocsparse_doti` computes the dot product of the sparse vector \(x\) with the dense vector \(y\), such that

  \[ \text{result} := y^T x \]

      for(i = 0; i < nnz; ++i)
      {
          result += x_val[i] * y[x_ind[i]];
      }

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - nnz – [in] number of non-zero entries of vector \(x\).

    - x_val – [in] array of `nnz` values.

    - x_ind – [in] array of `nnz` elements containing the indices of the non-zero values of \(x\).

    - y – [in] array of values in dense format.

    - result – [out] pointer to the result, can be host or device memory

    - idx_base – [in] rocsparse_index_base_zero or rocsparse_index_base_one.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_value – `idx_base` is invalid.

    - rocsparse_status_invalid_size – `nnz` is invalid.

    - rocsparse_status_invalid_pointer – `x_val`, `x_ind`, `y` or `result` pointer is invalid.

    - rocsparse_status_memory_error – the buffer for the dot product reduction could not be allocated.

    - rocsparse_status_internal_error – an internal error occurred.

### rocsparse_dotci()

rocsparse_status rocsparse_cdotci(rocsparse_handle handle, rocsparse_int nnz, const rocsparse_float_complex *x_val, const rocsparse_int *x_ind, const rocsparse_float_complex *y, rocsparse_float_complex *result, rocsparse_index_base idx_base)

rocsparse_status rocsparse_zdotci(rocsparse_handle handle, rocsparse_int nnz, const rocsparse_double_complex *x_val, const rocsparse_int *x_ind, const rocsparse_double_complex *y, rocsparse_double_complex *result, rocsparse_index_base idx_base)

  Compute the dot product of a complex conjugate sparse vector with a dense vector.

  `rocsparse_dotci` computes the dot product of the complex conjugate sparse vector \(x\) with the dense vector \(y\), such that

  \[ \text{result} := \bar{x}^H y \]

      for(i = 0; i < nnz; ++i)
      {
          result += conj(x_val[i]) * y[x_ind[i]];
      }

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - nnz – [in] number of non-zero entries of vector \(x\).

    - x_val – [in] array of `nnz` values.

    - x_ind – [in] array of `nnz` elements containing the indices of the non-zero values of \(x\).

    - y – [in] array of values in dense format.

    - result – [out] pointer to the result, can be host or device memory

    - idx_base – [in] rocsparse_index_base_zero or rocsparse_index_base_one.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_value – `idx_base` is invalid.

    - rocsparse_status_invalid_size – `nnz` is invalid.

    - rocsparse_status_invalid_pointer – `x_val`, `x_ind`, `y` or `result` pointer is invalid.

    - rocsparse_status_memory_error – the buffer for the dot product reduction could not be allocated.

    - rocsparse_status_internal_error – an internal error occurred.

### rocsparse_gthr()

rocsparse_status rocsparse_sgthr(rocsparse_handle handle, rocsparse_int nnz, const float *y, float *x_val, const rocsparse_int *x_ind, rocsparse_index_base idx_base)

rocsparse_status rocsparse_dgthr(rocsparse_handle handle, rocsparse_int nnz, const double *y, double *x_val, const rocsparse_int *x_ind, rocsparse_index_base idx_base)

rocsparse_status rocsparse_cgthr(rocsparse_handle handle, rocsparse_int nnz, const rocsparse_float_complex *y, rocsparse_float_complex *x_val, const rocsparse_int *x_ind, rocsparse_index_base idx_base)

rocsparse_status rocsparse_zgthr(rocsparse_handle handle, rocsparse_int nnz, const rocsparse_double_complex *y, rocsparse_double_complex *x_val, const rocsparse_int *x_ind, rocsparse_index_base idx_base)

  Gather elements from a dense vector and store them into a sparse vector.

  `rocsparse_gthr` gathers the elements that are listed in `x_ind` from the dense vector \(y\) and stores them in the sparse vector \(x\).

      for(i = 0; i < nnz; ++i)
      {
          x_val[i] = y[x_ind[i]];
      }

  Note

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

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - nnz – [in] number of non-zero entries of \(x\).

    - y – [in] array of values in dense format.

    - x_val – [out] array of `nnz` elements containing the values of \(x\).

    - x_ind – [in] array of `nnz` elements containing the indices of the non-zero values of \(x\).

    - idx_base – [in] rocsparse_index_base_zero or rocsparse_index_base_one.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_value – `idx_base` is invalid.

    - rocsparse_status_invalid_size – `nnz` is invalid.

    - rocsparse_status_invalid_pointer – `y`, `x_val` or `x_ind` pointer is invalid.

### rocsparse_gthrz()

rocsparse_status rocsparse_sgthrz(rocsparse_handle handle, rocsparse_int nnz, float *y, float *x_val, const rocsparse_int *x_ind, rocsparse_index_base idx_base)

rocsparse_status rocsparse_dgthrz(rocsparse_handle handle, rocsparse_int nnz, double *y, double *x_val, const rocsparse_int *x_ind, rocsparse_index_base idx_base)

rocsparse_status rocsparse_cgthrz(rocsparse_handle handle, rocsparse_int nnz, rocsparse_float_complex *y, rocsparse_float_complex *x_val, const rocsparse_int *x_ind, rocsparse_index_base idx_base)

rocsparse_status rocsparse_zgthrz(rocsparse_handle handle, rocsparse_int nnz, rocsparse_double_complex *y, rocsparse_double_complex *x_val, const rocsparse_int *x_ind, rocsparse_index_base idx_base)

  Gather and zero out elements from a dense vector and store them into a sparse vector.

  `rocsparse_gthrz` gathers the elements that are listed in `x_ind` from the dense vector \(y\) and stores them in the sparse vector \(x\). The gathered elements in \(y\) are replaced by zero.

      for(i = 0; i < nnz; ++i)
      {
          x_val[i]    = y[x_ind[i]];
          y[x_ind[i]] = 0;
      }

  Note

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

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - nnz – [in] number of non-zero entries of \(x\).

    - y – [inout] array of values in dense format.

    - x_val – [out] array of `nnz` elements containing the non-zero values of \(x\).

    - x_ind – [in] array of `nnz` elements containing the indices of the non-zero values of \(x\).

    - idx_base – [in] rocsparse_index_base_zero or rocsparse_index_base_one.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_value – `idx_base` is invalid.

    - rocsparse_status_invalid_size – `nnz` is invalid.

    - rocsparse_status_invalid_pointer – `y`, `x_val` or `x_ind` pointer is invalid.

### rocsparse_roti()

rocsparse_status rocsparse_sroti(rocsparse_handle handle, rocsparse_int nnz, float *x_val, const rocsparse_int *x_ind, float *y, const float *c, const float *s, rocsparse_index_base idx_base)

rocsparse_status rocsparse_droti(rocsparse_handle handle, rocsparse_int nnz, double *x_val, const rocsparse_int *x_ind, double *y, const double *c, const double *s, rocsparse_index_base idx_base)

  Apply Givens rotation to a dense and a sparse vector.

  `rocsparse_roti` applies the Givens rotation matrix \(G\) to the sparse vector \(x\) and the dense vector \(y\), where

  \[\begin{split} G = \begin{pmatrix} c & s \\ -s & c \end{pmatrix} \end{split}\]

      for(i = 0; i < nnz; ++i)
      {
          x_tmp = x_val[i];
          y_tmp = y[x_ind[i]];

          x_val[i]    = c * x_tmp + s * y_tmp;
          y[x_ind[i]] = c * y_tmp - s * x_tmp;
      }

  Note

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

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - nnz – [in] number of non-zero entries of \(x\).

    - x_val – [inout] array of `nnz` elements containing the non-zero values of \(x\).

    - x_ind – [in] array of `nnz` elements containing the indices of the non-zero values of \(x\).

    - y – [inout] array of values in dense format.

    - c – [in] pointer to the cosine element of \(G\), can be on host or device.

    - s – [in] pointer to the sine element of \(G\), can be on host or device.

    - idx_base – [in] rocsparse_index_base_zero or rocsparse_index_base_one.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_value – `idx_base` is invalid.

    - rocsparse_status_invalid_size – `nnz` is invalid.

    - rocsparse_status_invalid_pointer – `c`, `s`, `x_val`, `x_ind` or `y` pointer is invalid.

### rocsparse_sctr()

rocsparse_status rocsparse_ssctr(rocsparse_handle handle, rocsparse_int nnz, const float *x_val, const rocsparse_int *x_ind, float *y, rocsparse_index_base idx_base)

rocsparse_status rocsparse_dsctr(rocsparse_handle handle, rocsparse_int nnz, const double *x_val, const rocsparse_int *x_ind, double *y, rocsparse_index_base idx_base)

rocsparse_status rocsparse_csctr(rocsparse_handle handle, rocsparse_int nnz, const rocsparse_float_complex *x_val, const rocsparse_int *x_ind, rocsparse_float_complex *y, rocsparse_index_base idx_base)

rocsparse_status rocsparse_zsctr(rocsparse_handle handle, rocsparse_int nnz, const rocsparse_double_complex *x_val, const rocsparse_int *x_ind, rocsparse_double_complex *y, rocsparse_index_base idx_base)

  Scatter elements from a dense vector across a sparse vector.

  `rocsparse_sctr` scatters the elements that are listed in `x_ind` from the sparse vector \(x\) into the dense vector \(y\). Indices of \(y\) that are not listed in `x_ind` remain unchanged.

      for(i = 0; i < nnz; ++i)
      {
          y[x_ind[i]] = x_val[i];
      }

  Note

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

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - nnz – [in] number of non-zero entries of \(x\).

    - x_val – [in] array of `nnz` elements containing the non-zero values of \(x\).

    - x_ind – [in] array of `nnz` elements containing the indices of the non-zero values of x.

    - y – [inout] array of values in dense format.

    - idx_base – [in] rocsparse_index_base_zero or rocsparse_index_base_one.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_value – `idx_base` is invalid.

    - rocsparse_status_invalid_size – `nnz` is invalid.

    - rocsparse_status_invalid_pointer – `x_val`, `x_ind` or `y` pointer is invalid.

## Sparse Level 2 Functions

This module holds all sparse level 2 routines.

The sparse level 2 routines describe operations between a matrix in sparse format and a vector in dense format.

### rocsparse_bsrmv_ex_analysis()

rocsparse_status rocsparse_sbsrmv_ex_analysis(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const rocsparse_mat_descr descr, const float *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info)

rocsparse_status rocsparse_dbsrmv_ex_analysis(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const rocsparse_mat_descr descr, const double *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info)

rocsparse_status rocsparse_cbsrmv_ex_analysis(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const rocsparse_mat_descr descr, const rocsparse_float_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info)

rocsparse_status rocsparse_zbsrmv_ex_analysis(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const rocsparse_mat_descr descr, const rocsparse_double_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info)

  Sparse matrix vector multiplication using BSR storage format.

  `rocsparse_bsrmv_ex_analysis` performs the analysis step for rocsparse_sbsrmv(), rocsparse_dbsrmv(), rocsparse_cbsrmv() and rocsparse_zbsrmv(). It is expected that this function will be executed only once for a given matrix and particular operation type. The gathered analysis meta data can be cleared by rocsparse_bsrmv_ex_clear().

  Note

  If the matrix sparsity pattern changes, the gathered information will become invalid.

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - dir – [in] matrix storage of BSR blocks.

    - trans – [in] matrix operation type.

    - mb – [in] number of block rows of the sparse BSR matrix.

    - nb – [in] number of block columns of the sparse BSR matrix.

    - nnzb – [in] number of non-zero blocks of the sparse BSR matrix.

    - descr – [in] descriptor of the sparse BSR matrix. Currently, only rocsparse_matrix_type_general is supported.

    - bsr_val – [in] array of `nnzb` blocks of the sparse BSR matrix.

    - bsr_row_ptr – [in] array of `mb+1` elements that point to the start of every block row of the sparse BSR matrix.

    - bsr_col_ind – [in] array of `nnzb` elements containing the block column indices of the sparse BSR matrix.

    - block_dim – [in] block dimension of the sparse BSR matrix.

    - info – [out] structure that holds the information collected during the analysis step.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `mb`, `nb` or `nnzb` is invalid.

    - rocsparse_status_invalid_pointer – `descr`, `bsr_val`, `bsr_row_ptr`, `bsr_col_ind` or `info` pointer is invalid.

    - rocsparse_status_memory_error – the buffer for the gathered information could not be allocated.

    - rocsparse_status_internal_error – an internal error occurred.

    - rocsparse_status_not_implemented – `trans` != rocsparse_operation_none or rocsparse_matrix_type != rocsparse_matrix_type_general.

### rocsparse_bsrmv_ex()

rocsparse_status rocsparse_sbsrmv_ex(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const float *alpha, const rocsparse_mat_descr descr, const float *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, const float *x, const float *beta, float *y)

rocsparse_status rocsparse_dbsrmv_ex(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const double *alpha, const rocsparse_mat_descr descr, const double *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, const double *x, const double *beta, double *y)

rocsparse_status rocsparse_cbsrmv_ex(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const rocsparse_float_complex *alpha, const rocsparse_mat_descr descr, const rocsparse_float_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, const rocsparse_float_complex *x, const rocsparse_float_complex *beta, rocsparse_float_complex *y)

rocsparse_status rocsparse_zbsrmv_ex(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const rocsparse_double_complex *alpha, const rocsparse_mat_descr descr, const rocsparse_double_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, const rocsparse_double_complex *x, const rocsparse_double_complex *beta, rocsparse_double_complex *y)

  Sparse matrix vector multiplication using BSR storage format.

  `rocsparse_bsrmv_ex` multiplies the scalar \(\alpha\) with a sparse \((mb \cdot \text{block_dim}) \times (nb \cdot \text{block_dim})\) matrix, defined in BSR storage format, and the dense vector \(x\) and adds the result to the dense vector \(y\) that is multiplied by the scalar \(\beta\), such that

  \[ y := \alpha \cdot op(A) \cdot x + \beta \cdot y, \]
  with
  \[\begin{split} op(A) = \left\{ \begin{array}{ll} A, & \text{if trans == rocsparse_operation_none} \\ A^T, & \text{if trans == rocsparse_operation_transpose} \\ A^H, & \text{if trans == rocsparse_operation_conjugate_transpose} \end{array} \right. \end{split}\]

  Note

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

  Note

  Currently, only `trans` == rocsparse_operation_none is supported.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - dir – [in] matrix storage of BSR blocks.

    - trans – [in] matrix operation type.

    - mb – [in] number of block rows of the sparse BSR matrix.

    - nb – [in] number of block columns of the sparse BSR matrix.

    - nnzb – [in] number of non-zero blocks of the sparse BSR matrix.

    - alpha – [in] scalar \(\alpha\).

    - descr – [in] descriptor of the sparse BSR matrix. Currently, only rocsparse_matrix_type_general is supported.

    - bsr_val – [in] array of `nnzb` blocks of the sparse BSR matrix.

    - bsr_row_ptr – [in] array of `mb+1` elements that point to the start of every block row of the sparse BSR matrix.

    - bsr_col_ind – [in] array of `nnzb` elements containing the block column indices of the sparse BSR matrix.

    - block_dim – [in] block dimension of the sparse BSR matrix.

    - x – [in] array of `nb*block_dim` elements ( \(op(A) = A\)) or `mb*block_dim` elements ( \(op(A) = A^T\) or \(op(A) = A^H\)).

    - beta – [in] scalar \(\beta\).

    - y – [inout] array of `mb*block_dim` elements ( \(op(A) = A\)) or `nb*block_dim` elements ( \(op(A) = A^T\) or \(op(A) = A^H\)).

    - info – [out] structure that holds the information collected during the analysis step.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `mb`, `nb`, `nnzb` or `block_dim` is invalid.

    - rocsparse_status_invalid_pointer – `descr`, `alpha`, `bsr_val`, `bsr_row_ind`, `bsr_col_ind`, `x`, `beta` or `y` pointer is invalid.

    - rocsparse_status_arch_mismatch – the device is not supported.

    - rocsparse_status_not_implemented – `trans` != rocsparse_operation_none or rocsparse_matrix_type != rocsparse_matrix_type_general.

### rocsparse_bsrmv()

rocsparse_status rocsparse_sbsrmv(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const float *alpha, const rocsparse_mat_descr descr, const float *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, const float *x, const float *beta, float *y)

rocsparse_status rocsparse_dbsrmv(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const double *alpha, const rocsparse_mat_descr descr, const double *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, const double *x, const double *beta, double *y)

rocsparse_status rocsparse_cbsrmv(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const rocsparse_float_complex *alpha, const rocsparse_mat_descr descr, const rocsparse_float_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, const rocsparse_float_complex *x, const rocsparse_float_complex *beta, rocsparse_float_complex *y)

rocsparse_status rocsparse_zbsrmv(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const rocsparse_double_complex *alpha, const rocsparse_mat_descr descr, const rocsparse_double_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, const rocsparse_double_complex *x, const rocsparse_double_complex *beta, rocsparse_double_complex *y)

  Sparse matrix vector multiplication using BSR storage format.

  `rocsparse_bsrmv` multiplies the scalar \(\alpha\) with a sparse \((mb \cdot \text{block_dim}) \times (nb \cdot \text{block_dim})\) matrix, defined in BSR storage format, and the dense vector \(x\) and adds the result to the dense vector \(y\) that is multiplied by the scalar \(\beta\), such that

  \[ y := \alpha \cdot op(A) \cdot x + \beta \cdot y, \]
  with
  \[\begin{split} op(A) = \left\{ \begin{array}{ll} A, & \text{if trans == rocsparse_operation_none} \\ A^T, & \text{if trans == rocsparse_operation_transpose} \\ A^H, & \text{if trans == rocsparse_operation_conjugate_transpose} \end{array} \right. \end{split}\]

  Note

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

  Note

  Currently, only `trans` == rocsparse_operation_none is supported.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - dir – [in] matrix storage of BSR blocks.

    - trans – [in] matrix operation type.

    - mb – [in] number of block rows of the sparse BSR matrix.

    - nb – [in] number of block columns of the sparse BSR matrix.

    - nnzb – [in] number of non-zero blocks of the sparse BSR matrix.

    - alpha – [in] scalar \(\alpha\).

    - descr – [in] descriptor of the sparse BSR matrix. Currently, only rocsparse_matrix_type_general is supported.

    - bsr_val – [in] array of `nnzb` blocks of the sparse BSR matrix.

    - bsr_row_ptr – [in] array of `mb+1` elements that point to the start of every block row of the sparse BSR matrix.

    - bsr_col_ind – [in] array of `nnzb` elements containing the block column indices of the sparse BSR matrix.

    - block_dim – [in] block dimension of the sparse BSR matrix.

    - x – [in] array of `nb*block_dim` elements ( \(op(A) = A\)) or `mb*block_dim` elements ( \(op(A) = A^T\) or \(op(A) = A^H\)).

    - beta – [in] scalar \(\beta\).

    - y – [inout] array of `mb*block_dim` elements ( \(op(A) = A\)) or `nb*block_dim` elements ( \(op(A) = A^T\) or \(op(A) = A^H\)).

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `mb`, `nb`, `nnzb` or `block_dim` is invalid.

    - rocsparse_status_invalid_pointer – `descr`, `alpha`, `bsr_val`, `bsr_row_ind`, `bsr_col_ind`, `x`, `beta` or `y` pointer is invalid.

    - rocsparse_status_arch_mismatch – the device is not supported.

    - rocsparse_status_not_implemented – `trans` != rocsparse_operation_none or rocsparse_matrix_type != rocsparse_matrix_type_general.

### rocsparse_bsrxmv()

rocsparse_status rocsparse_sbsrxmv(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans, rocsparse_int size_of_mask, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const float *alpha, const rocsparse_mat_descr descr, const float *bsr_val, const rocsparse_int *bsr_mask_ptr, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_end_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, const float *x, const float *beta, float *y)

rocsparse_status rocsparse_dbsrxmv(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans, rocsparse_int size_of_mask, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const double *alpha, const rocsparse_mat_descr descr, const double *bsr_val, const rocsparse_int *bsr_mask_ptr, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_end_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, const double *x, const double *beta, double *y)

rocsparse_status rocsparse_cbsrxmv(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans, rocsparse_int size_of_mask, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const rocsparse_float_complex *alpha, const rocsparse_mat_descr descr, const rocsparse_float_complex *bsr_val, const rocsparse_int *bsr_mask_ptr, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_end_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, const rocsparse_float_complex *x, const rocsparse_float_complex *beta, rocsparse_float_complex *y)

rocsparse_status rocsparse_zbsrxmv(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans, rocsparse_int size_of_mask, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const rocsparse_double_complex *alpha, const rocsparse_mat_descr descr, const rocsparse_double_complex *bsr_val, const rocsparse_int *bsr_mask_ptr, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_end_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, const rocsparse_double_complex *x, const rocsparse_double_complex *beta, rocsparse_double_complex *y)

  Sparse matrix vector multiplication with mask operation using BSR storage format.

  `rocsparse_bsrxmv` multiplies the scalar \(\alpha\) with a sparse \((mb \cdot \text{block_dim}) \times (nb \cdot \text{block_dim})\) modified matrix, defined in BSR storage format, and the dense vector \(x\) and adds the result to the dense vector \(y\) that is multiplied by the scalar \(\beta\), such that

  \[ y := \left( \alpha \cdot op(A) \cdot x + \beta \cdot y \right)\left( \text{mask} \right), \]
  with
  \[\begin{split} op(A) = \left\{ \begin{array}{ll} A, & \text{if trans == rocsparse_operation_none} \\ A^T, & \text{if trans == rocsparse_operation_transpose} \\ A^H, & \text{if trans == rocsparse_operation_conjugate_transpose} \end{array} \right. \end{split}\]

  The \(\text{mask}\) is defined as an array of block row indices. The input sparse matrix is defined with a modified BSR storage format where the beginning and the end of each row is defined with two arrays, `bsr_row_ptr` and `bsr_end_ptr` (both of size `mb`), rather the usual `bsr_row_ptr` of size `mb+1`.

  Note

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

  Note

  Currently, only `trans` == rocsparse_operation_none is supported. Currently, `block_dim==1` is not supported.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - dir – [in] matrix storage of BSR blocks.

    - trans – [in] matrix operation type.

    - size_of_mask – [in] number of updated block rows of the array `y`.

    - mb – [in] number of block rows of the sparse BSR matrix.

    - nb – [in] number of block columns of the sparse BSR matrix.

    - nnzb – [in] number of non-zero blocks of the sparse BSR matrix.

    - alpha – [in] scalar \(\alpha\).

    - descr – [in] descriptor of the sparse BSR matrix. Currently, only rocsparse_matrix_type_general is supported.

    - bsr_val – [in] array of `nnzb` blocks of the sparse BSR matrix.

    - bsr_mask_ptr – [in] array of `size_of_mask` elements that give the indices of the updated block rows.

    - bsr_row_ptr – [in] array of `mb` elements that point to the start of every block row of the sparse BSR matrix.

    - bsr_end_ptr – [in] array of `mb` elements that point to the end of every block row of the sparse BSR matrix.

    - bsr_col_ind – [in] array of `nnzb` elements containing the block column indices of the sparse BSR matrix.

    - block_dim – [in] block dimension of the sparse BSR matrix.

    - x – [in] array of `nb*block_dim` elements ( \(op(A) = A\)) or `mb*block_dim` elements ( \(op(A) = A^T\) or \(op(A) = A^H\)).

    - beta – [in] scalar \(\beta\).

    - y – [inout] array of `mb*block_dim` elements ( \(op(A) = A\)) or `nb*block_dim` elements ( \(op(A) = A^T\) or \(op(A) = A^H\)).

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `mb`, `nb`, `nnzb`, `block_dim` or `size_of_mask` is invalid.

    - rocsparse_status_invalid_value – `size_of_mask` is greater than `mb`.

    - rocsparse_status_invalid_pointer – `descr`, `alpha`, `bsr_val`, `bsr_row_ind`, `bsr_col_ind`, `x`, `beta` or `y` pointer is invalid.

    - rocsparse_status_arch_mismatch – the device is not supported.

    - rocsparse_status_not_implemented – `block_dim==1`, `trans` != rocsparse_operation_none or rocsparse_matrix_type != rocsparse_matrix_type_general.

### rocsparse_bsrsv_zero_pivot()

rocsparse_status rocsparse_bsrsv_zero_pivot(rocsparse_handle handle, rocsparse_mat_info info, rocsparse_int *position)

  Sparse triangular solve using BSR storage format.

  `rocsparse_bsrsv_zero_pivot` returns rocsparse_status_zero_pivot, if either a structural or numerical zero has been found during rocsparse_sbsrsv_solve(), rocsparse_dbsrsv_solve(), rocsparse_cbsrsv_solve() or rocsparse_zbsrsv_solve() computation. The first zero pivot \(j\) at \(A_{j,j}\) is stored in `position`, using same index base as the BSR matrix.

  `position` can be in host or device memory. If no zero pivot has been found, `position` is set to -1 and rocsparse_status_success is returned instead.

  Note

  `rocsparse_bsrsv_zero_pivot` is a blocking function. It might influence performance negatively.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - info – [in] structure that holds the information collected during the analysis step.

    - position – [inout] pointer to zero pivot \(j\), can be in host or device memory.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_pointer – `info` or `position` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

    - rocsparse_status_zero_pivot – zero pivot has been found.

### rocsparse_bsrsv_buffer_size()

rocsparse_status rocsparse_sbsrsv_buffer_size(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans, rocsparse_int mb, rocsparse_int nnzb, const rocsparse_mat_descr descr, const float *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, size_t *buffer_size)

rocsparse_status rocsparse_dbsrsv_buffer_size(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans, rocsparse_int mb, rocsparse_int nnzb, const rocsparse_mat_descr descr, const double *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, size_t *buffer_size)

rocsparse_status rocsparse_cbsrsv_buffer_size(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans, rocsparse_int mb, rocsparse_int nnzb, const rocsparse_mat_descr descr, const rocsparse_float_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, size_t *buffer_size)

rocsparse_status rocsparse_zbsrsv_buffer_size(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans, rocsparse_int mb, rocsparse_int nnzb, const rocsparse_mat_descr descr, const rocsparse_double_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, size_t *buffer_size)

  Sparse triangular solve using BSR storage format.

  `rocsparse_bsrsv_buffer_size` returns the size of the temporary storage buffer that is required by rocsparse_sbsrsv_analysis(), rocsparse_dbsrsv_analysis(), rocsparse_cbsrsv_analysis(), rocsparse_zbsrsv_analysis(), rocsparse_sbsrsv_solve(), rocsparse_dbsrsv_solve(), rocsparse_cbsrsv_solve() and rocsparse_zbsrsv_solve(). The temporary storage buffer must be allocated by the user.

  Note

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

  Note

  This routine supports execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - dir – [in] matrix storage of BSR blocks.

    - trans – [in] matrix operation type.

    - mb – [in] number of block rows of the sparse BSR matrix.

    - nnzb – [in] number of non-zero blocks of the sparse BSR matrix.

    - descr – [in] descriptor of the sparse BSR matrix.

    - bsr_val – [in] array of `nnzb` blocks of the sparse BSR matrix.

    - bsr_row_ptr – [in] array of `mb+1` elements that point to the start of every block row of the sparse BSR matrix.

    - bsr_col_ind – [in] array of `nnz` containing the block column indices of the sparse BSR matrix.

    - block_dim – [in] block dimension of the sparse BSR matrix.

    - info – [out] structure that holds the information collected during the analysis step.

    - buffer_size – [out] number of bytes of the temporary storage buffer required by rocsparse_sbsrsv_analysis(), rocsparse_dbsrsv_analysis(), rocsparse_cbsrsv_analysis(), rocsparse_zbsrsv_analysis(), rocsparse_sbsrsv_solve(), rocsparse_dbsrsv_solve(), rocsparse_cbsrsv_solve() and rocsparse_zbsrsv_solve().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `mb`, `nnzb` or `block_dim` is invalid.

    - rocsparse_status_invalid_pointer – `descr`, `bsr_val`, `bsr_row_ptr`, `bsr_col_ind`, `info` or `buffer_size` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

    - rocsparse_status_not_implemented – `trans` == rocsparse_operation_conjugate_transpose or rocsparse_matrix_type != rocsparse_matrix_type_general.

### rocsparse_bsrsv_analysis()

rocsparse_status rocsparse_sbsrsv_analysis(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans, rocsparse_int mb, rocsparse_int nnzb, const rocsparse_mat_descr descr, const float *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, rocsparse_analysis_policy analysis, rocsparse_solve_policy solve, void *temp_buffer)

rocsparse_status rocsparse_dbsrsv_analysis(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans, rocsparse_int mb, rocsparse_int nnzb, const rocsparse_mat_descr descr, const double *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, rocsparse_analysis_policy analysis, rocsparse_solve_policy solve, void *temp_buffer)

rocsparse_status rocsparse_cbsrsv_analysis(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans, rocsparse_int mb, rocsparse_int nnzb, const rocsparse_mat_descr descr, const rocsparse_float_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, rocsparse_analysis_policy analysis, rocsparse_solve_policy solve, void *temp_buffer)

rocsparse_status rocsparse_zbsrsv_analysis(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans, rocsparse_int mb, rocsparse_int nnzb, const rocsparse_mat_descr descr, const rocsparse_double_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, rocsparse_analysis_policy analysis, rocsparse_solve_policy solve, void *temp_buffer)

  Sparse triangular solve using BSR storage format.

  `rocsparse_bsrsv_analysis` performs the analysis step for rocsparse_sbsrsv_solve(), rocsparse_dbsrsv_solve(), rocsparse_cbsrsv_solve() and rocsparse_zbsrsv_solve(). It is expected that this function will be executed only once for a given matrix and particular operation type. The analysis meta data can be cleared by rocsparse_bsrsv_clear().

  `rocsparse_bsrsv_analysis` can share its meta data with rocsparse_sbsrsm_analysis(), rocsparse_dbsrsm_analysis(), rocsparse_cbsrsm_analysis(), rocsparse_zbsrsm_analysis(), rocsparse_sbsrilu0_analysis(), rocsparse_dbsrilu0_analysis(), rocsparse_cbsrilu0_analysis(), rocsparse_zbsrilu0_analysis(), rocsparse_sbsric0_analysis(), rocsparse_dbsric0_analysis(), rocsparse_cbsric0_analysis() and rocsparse_zbsric0_analysis(). Selecting rocsparse_analysis_policy_reuse policy can greatly improve computation performance of meta data. However, the user need to make sure that the sparsity pattern remains unchanged. If this cannot be assured, rocsparse_analysis_policy_force has to be used.

  Note

  If the matrix sparsity pattern changes, the gathered information will become invalid.

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - dir – [in] matrix storage of BSR blocks.

    - trans – [in] matrix operation type.

    - mb – [in] number of block rows of the sparse BSR matrix.

    - nnzb – [in] number of non-zero blocks of the sparse BSR matrix.

    - descr – [in] descriptor of the sparse BSR matrix.

    - bsr_val – [in] array of `nnzb` blocks of the sparse BSR matrix.

    - bsr_row_ptr – [in] array of `mb+1` elements that point to the start of every block row of the sparse BSR matrix.

    - bsr_col_ind – [in] array of `nnz` containing the block column indices of the sparse BSR matrix.

    - block_dim – [in] block dimension of the sparse BSR matrix.

    - info – [out] structure that holds the information collected during the analysis step.

    - analysis – [in] rocsparse_analysis_policy_reuse or rocsparse_analysis_policy_force.

    - solve – [in] rocsparse_solve_policy_auto.

    - temp_buffer – [in] temporary storage buffer allocated by the user.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `mb`, `nnzb` or `block_dim` is invalid.

    - rocsparse_status_invalid_pointer – `descr`, `bsr_row_ptr`, `bsr_col_ind`, `info` or `temp_buffer` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

    - rocsparse_status_not_implemented – `trans` == rocsparse_operation_conjugate_transpose or rocsparse_matrix_type != rocsparse_matrix_type_general.

### rocsparse_bsrsv_solve()

rocsparse_status rocsparse_sbsrsv_solve(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans, rocsparse_int mb, rocsparse_int nnzb, const float *alpha, const rocsparse_mat_descr descr, const float *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, const float *x, float *y, rocsparse_solve_policy policy, void *temp_buffer)

rocsparse_status rocsparse_dbsrsv_solve(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans, rocsparse_int mb, rocsparse_int nnzb, const double *alpha, const rocsparse_mat_descr descr, const double *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, const double *x, double *y, rocsparse_solve_policy policy, void *temp_buffer)

rocsparse_status rocsparse_cbsrsv_solve(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans, rocsparse_int mb, rocsparse_int nnzb, const rocsparse_float_complex *alpha, const rocsparse_mat_descr descr, const rocsparse_float_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, const rocsparse_float_complex *x, rocsparse_float_complex *y, rocsparse_solve_policy policy, void *temp_buffer)

rocsparse_status rocsparse_zbsrsv_solve(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans, rocsparse_int mb, rocsparse_int nnzb, const rocsparse_double_complex *alpha, const rocsparse_mat_descr descr, const rocsparse_double_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, const rocsparse_double_complex *x, rocsparse_double_complex *y, rocsparse_solve_policy policy, void *temp_buffer)

  Sparse triangular solve using BSR storage format.

  `rocsparse_bsrsv_solve` solves a sparse triangular linear system of a sparse \(m \times m\) matrix, defined in BSR storage format, a dense solution vector \(y\) and the right-hand side \(x\) that is multiplied by \(\alpha\), such that

  \[ op(A) \cdot y = \alpha \cdot x, \]
  with
  \[\begin{split} op(A) = \left\{ \begin{array}{ll} A, & \text{if trans == rocsparse_operation_none} \\ A^T, & \text{if trans == rocsparse_operation_transpose} \\ A^H, & \text{if trans == rocsparse_operation_conjugate_transpose} \end{array} \right. \end{split}\]

  `rocsparse_bsrsv_solve` requires a user allocated temporary buffer. Its size is returned by rocsparse_sbsrsv_buffer_size(), rocsparse_dbsrsv_buffer_size(), rocsparse_cbsrsv_buffer_size() or rocsparse_zbsrsv_buffer_size(). Furthermore, analysis meta data is required. It can be obtained by rocsparse_sbsrsv_analysis(), rocsparse_dbsrsv_analysis(), rocsparse_cbsrsv_analysis() or rocsparse_zbsrsv_analysis(). `rocsparse_bsrsv_solve` reports the first zero pivot (either numerical or structural zero). The zero pivot status can be checked calling rocsparse_bsrsv_zero_pivot(). If rocsparse_diag_type == rocsparse_diag_type_unit, no zero pivot will be reported, even if \(A_{j,j} = 0\) for some \(j\).

  Example

    Consider the lower triangular \(m \times m\) matrix \(L\), stored in BSR storage format with unit diagonal. The following example solves \(L \cdot y = x\).

        // Create rocSPARSE handle
        rocsparse_handle handle;
        rocsparse_create_handle(&handle);

        // Create matrix descriptor
        rocsparse_mat_descr descr;
        rocsparse_create_mat_descr(&descr);
        rocsparse_set_mat_fill_mode(descr, rocsparse_fill_mode_lower);
        rocsparse_set_mat_diag_type(descr, rocsparse_diag_type_unit);

        // Create matrix info structure
        rocsparse_mat_info info;
        rocsparse_create_mat_info(&info);

        // Obtain required buffer size
        size_t buffer_size;
        rocsparse_dbsrsv_buffer_size(handle,
                                     rocsparse_direction_column,
                                     rocsparse_operation_none,
                                     mb,
                                     nnzb,
                                     descr,
                                     bsr_val,
                                     bsr_row_ptr,
                                     bsr_col_ind,
                                     block_dim,
                                     info,
                                     &buffer_size);

        // Allocate temporary buffer
        void* temp_buffer;
        hipMalloc(&temp_buffer, buffer_size);

        // Perform analysis step
        rocsparse_dbsrsv_analysis(handle,
                                  rocsparse_direction_column,
                                  rocsparse_operation_none,
                                  mb,
                                  nnzb,
                                  descr,
                                  bsr_val,
                                  bsr_row_ptr,
                                  bsr_col_ind,
                                  block_dim,
                                  info,
                                  rocsparse_analysis_policy_reuse,
                                  rocsparse_solve_policy_auto,
                                  temp_buffer);

        // Solve Ly = x
        rocsparse_dbsrsv_solve(handle,
                               rocsparse_direction_column,
                               rocsparse_operation_none,
                               mb,
                               nnzb,
                               &alpha,
                               descr,
                               bsr_val,
                               bsr_row_ptr,
                               bsr_col_ind,
                               block_dim,
                               info,
                               x,
                               y,
                               rocsparse_solve_policy_auto,
                               temp_buffer);

        // No zero pivot should be found, with L having unit diagonal

        // Clean up
        hipFree(temp_buffer);
        rocsparse_destroy_mat_info(info);
        rocsparse_destroy_mat_descr(descr);
        rocsparse_destroy_handle(handle);

  Note

  The sparse BSR matrix has to be sorted.

  Note

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

  Note

  Currently, only `trans` == rocsparse_operation_none and `trans` == rocsparse_operation_transpose is supported.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - dir – [in] matrix storage of BSR blocks.

    - trans – [in] matrix operation type.

    - mb – [in] number of block rows of the sparse BSR matrix.

    - nnzb – [in] number of non-zero blocks of the sparse BSR matrix.

    - alpha – [in] scalar \(\alpha\).

    - descr – [in] descriptor of the sparse BSR matrix.

    - bsr_val – [in] array of `nnzb` blocks of the sparse BSR matrix.

    - bsr_row_ptr – [in] array of `mb+1` elements that point to the start of every block row of the sparse BSR matrix.

    - bsr_col_ind – [in] array of `nnz` containing the block column indices of the sparse BSR matrix.

    - block_dim – [in] block dimension of the sparse BSR matrix.

    - info – [in] structure that holds the information collected during the analysis step.

    - x – [in] array of `m` elements, holding the right-hand side.

    - y – [out] array of `m` elements, holding the solution.

    - policy – [in] rocsparse_solve_policy_auto.

    - temp_buffer – [in] temporary storage buffer allocated by the user.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `mb`, `nnzb` or `block_dim` is invalid.

    - rocsparse_status_invalid_pointer – `descr`, `alpha`, `bsr_val`, `bsr_row_ptr`, `bsr_col_ind`, `x` or `y` pointer is invalid.

    - rocsparse_status_arch_mismatch – the device is not supported.

    - rocsparse_status_internal_error – an internal error occurred.

    - rocsparse_status_not_implemented – `trans` == rocsparse_operation_conjugate_transpose or rocsparse_matrix_type != rocsparse_matrix_type_general.

### rocsparse_bsrsv_clear()

rocsparse_status rocsparse_bsrsv_clear(rocsparse_handle handle, rocsparse_mat_info info)

  Sparse triangular solve using BSR storage format.

  `rocsparse_bsrsv_clear` deallocates all memory that was allocated by rocsparse_sbsrsv_analysis(), rocsparse_dbsrsv_analysis(), rocsparse_cbsrsv_analysis() or rocsparse_zbsrsv_analysis(). This is especially useful, if memory is an issue and the analysis data is not required for further computation, e.g. when switching to another sparse matrix format. Calling `rocsparse_bsrsv_clear` is optional. All allocated resources will be cleared, when the opaque rocsparse_mat_info struct is destroyed using rocsparse_destroy_mat_info().

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - info – [inout] structure that holds the information collected during the analysis step.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_pointer – `info` pointer is invalid.

    - rocsparse_status_memory_error – the buffer holding the meta data could not be deallocated.

    - rocsparse_status_internal_error – an internal error occurred.

### rocsparse_coomv()

rocsparse_status rocsparse_scoomv(rocsparse_handle handle, rocsparse_operation trans, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const float *alpha, const rocsparse_mat_descr descr, const float *coo_val, const rocsparse_int *coo_row_ind, const rocsparse_int *coo_col_ind, const float *x, const float *beta, float *y)

rocsparse_status rocsparse_dcoomv(rocsparse_handle handle, rocsparse_operation trans, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const double *alpha, const rocsparse_mat_descr descr, const double *coo_val, const rocsparse_int *coo_row_ind, const rocsparse_int *coo_col_ind, const double *x, const double *beta, double *y)

rocsparse_status rocsparse_ccoomv(rocsparse_handle handle, rocsparse_operation trans, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const rocsparse_float_complex *alpha, const rocsparse_mat_descr descr, const rocsparse_float_complex *coo_val, const rocsparse_int *coo_row_ind, const rocsparse_int *coo_col_ind, const rocsparse_float_complex *x, const rocsparse_float_complex *beta, rocsparse_float_complex *y)

rocsparse_status rocsparse_zcoomv(rocsparse_handle handle, rocsparse_operation trans, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const rocsparse_double_complex *alpha, const rocsparse_mat_descr descr, const rocsparse_double_complex *coo_val, const rocsparse_int *coo_row_ind, const rocsparse_int *coo_col_ind, const rocsparse_double_complex *x, const rocsparse_double_complex *beta, rocsparse_double_complex *y)

  Sparse matrix vector multiplication using COO storage format.

  `rocsparse_coomv` multiplies the scalar \(\alpha\) with a sparse \(m \times n\) matrix, defined in COO storage format, and the dense vector \(x\) and adds the result to the dense vector \(y\) that is multiplied by the scalar \(\beta\), such that

  \[ y := \alpha \cdot op(A) \cdot x + \beta \cdot y, \]
  with
  \[\begin{split} op(A) = \left\{ \begin{array}{ll} A, & \text{if trans == rocsparse_operation_none} \\ A^T, & \text{if trans == rocsparse_operation_transpose} \\ A^H, & \text{if trans == rocsparse_operation_conjugate_transpose} \end{array} \right. \end{split}\]

  The COO matrix has to be sorted by row indices. This can be achieved by using rocsparse_coosort_by_row().

      for(i = 0; i < m; ++i)
      {
          y[i] = beta * y[i];
      }

      for(i = 0; i < nnz; ++i)
      {
          y[coo_row_ind[i]] += alpha * coo_val[i] * x[coo_col_ind[i]];
      }

  Note

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

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - trans – [in] matrix operation type.

    - m – [in] number of rows of the sparse COO matrix.

    - n – [in] number of columns of the sparse COO matrix.

    - nnz – [in] number of non-zero entries of the sparse COO matrix.

    - alpha – [in] scalar \(\alpha\).

    - descr – [in] descriptor of the sparse COO matrix. Currently, only rocsparse_matrix_type_general is supported.

    - coo_val – [in] array of `nnz` elements of the sparse COO matrix.

    - coo_row_ind – [in] array of `nnz` elements containing the row indices of the sparse COO matrix.

    - coo_col_ind – [in] array of `nnz` elements containing the column indices of the sparse COO matrix.

    - x – [in] array of `n` elements ( \(op(A) = A\)) or `m` elements ( \(op(A) = A^T\) or \(op(A) = A^H\)).

    - beta – [in] scalar \(\beta\).

    - y – [inout] array of `m` elements ( \(op(A) = A\)) or `n` elements ( \(op(A) = A^T\) or \(op(A) = A^H\)).

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m`, `n` or `nnz` is invalid.

    - rocsparse_status_invalid_pointer – `descr`, `alpha`, `coo_val`, `coo_row_ind`, `coo_col_ind`, `x`, `beta` or `y` pointer is invalid.

    - rocsparse_status_arch_mismatch – the device is not supported.

    - rocsparse_status_not_implemented – rocsparse_matrix_type != rocsparse_matrix_type_general.

### rocsparse_csrmv_analysis()

rocsparse_status rocsparse_scsrmv_analysis(rocsparse_handle handle, rocsparse_operation trans, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const rocsparse_mat_descr descr, const float *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info)

rocsparse_status rocsparse_dcsrmv_analysis(rocsparse_handle handle, rocsparse_operation trans, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const rocsparse_mat_descr descr, const double *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info)

rocsparse_status rocsparse_ccsrmv_analysis(rocsparse_handle handle, rocsparse_operation trans, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const rocsparse_mat_descr descr, const rocsparse_float_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info)

rocsparse_status rocsparse_zcsrmv_analysis(rocsparse_handle handle, rocsparse_operation trans, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const rocsparse_mat_descr descr, const rocsparse_double_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info)

  Sparse matrix vector multiplication using CSR storage format.

  `rocsparse_csrmv_analysis` performs the analysis step for rocsparse_scsrmv(), rocsparse_dcsrmv(), rocsparse_ccsrmv() and rocsparse_zcsrmv(). It is expected that this function will be executed only once for a given matrix and particular operation type. The gathered analysis meta data can be cleared by rocsparse_csrmv_clear().

  Note

  If the matrix sparsity pattern changes, the gathered information will become invalid.

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - trans – [in] matrix operation type.

    - m – [in] number of rows of the sparse CSR matrix.

    - n – [in] number of columns of the sparse CSR matrix.

    - nnz – [in] number of non-zero entries of the sparse CSR matrix.

    - descr – [in] descriptor of the sparse CSR matrix.

    - csr_val – [in] array of `nnz` elements of the sparse CSR matrix.

    - csr_row_ptr – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix.

    - csr_col_ind – [in] array of `nnz` elements containing the column indices of the sparse CSR matrix.

    - info – [out] structure that holds the information collected during the analysis step.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m`, `n` or `nnz` is invalid.

    - rocsparse_status_invalid_pointer – `descr`, `csr_val`, `csr_row_ptr`, `csr_col_ind` or `info` pointer is invalid.

    - rocsparse_status_memory_error – the buffer for the gathered information could not be allocated.

    - rocsparse_status_internal_error – an internal error occurred.

    - rocsparse_status_not_implemented – if rocsparse_matrix_type is not one of rocsparse_matrix_type_general, rocsparse_matrix_type_symmetric, or rocsparse_matrix_type_triangular.

### rocsparse_csrmv()

rocsparse_status rocsparse_scsrmv(rocsparse_handle handle, rocsparse_operation trans, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const float *alpha, const rocsparse_mat_descr descr, const float *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, const float *x, const float *beta, float *y)

rocsparse_status rocsparse_dcsrmv(rocsparse_handle handle, rocsparse_operation trans, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const double *alpha, const rocsparse_mat_descr descr, const double *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, const double *x, const double *beta, double *y)

rocsparse_status rocsparse_ccsrmv(rocsparse_handle handle, rocsparse_operation trans, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const rocsparse_float_complex *alpha, const rocsparse_mat_descr descr, const rocsparse_float_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, const rocsparse_float_complex *x, const rocsparse_float_complex *beta, rocsparse_float_complex *y)

rocsparse_status rocsparse_zcsrmv(rocsparse_handle handle, rocsparse_operation trans, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const rocsparse_double_complex *alpha, const rocsparse_mat_descr descr, const rocsparse_double_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, const rocsparse_double_complex *x, const rocsparse_double_complex *beta, rocsparse_double_complex *y)

  Sparse matrix vector multiplication using CSR storage format.

  `rocsparse_csrmv` multiplies the scalar \(\alpha\) with a sparse \(m \times n\) matrix, defined in CSR storage format, and the dense vector \(x\) and adds the result to the dense vector \(y\) that is multiplied by the scalar \(\beta\), such that

  \[ y := \alpha \cdot op(A) \cdot x + \beta \cdot y, \]
  with
  \[\begin{split} op(A) = \left\{ \begin{array}{ll} A, & \text{if trans == rocsparse_operation_none} \\ A^T, & \text{if trans == rocsparse_operation_transpose} \\ A^H, & \text{if trans == rocsparse_operation_conjugate_transpose} \end{array} \right. \end{split}\]

  The `info` parameter is optional and contains information collected by rocsparse_scsrmv_analysis(), rocsparse_dcsrmv_analysis(), rocsparse_ccsrmv_analysis() or rocsparse_zcsrmv_analysis(). If present, the information will be used to speed up the `csrmv` computation. If `info` == `NULL`, general `csrmv` routine will be used instead.

      for(i = 0; i < m; ++i)
      {
          y[i] = beta * y[i];

          for(j = csr_row_ptr[i]; j < csr_row_ptr[i + 1]; ++j)
          {
              y[i] = y[i] + alpha * csr_val[j] * x[csr_col_ind[j]];
          }
      }

  Example

    This example performs a sparse matrix vector multiplication in CSR format using additional meta data to improve performance.

        // Create matrix info structure
        rocsparse_mat_info info;
        rocsparse_create_mat_info(&info);

        // Perform analysis step to obtain meta data
        rocsparse_scsrmv_analysis(handle,
                                  rocsparse_operation_none,
                                  m,
                                  n,
                                  nnz,
                                  descr,
                                  csr_val,
                                  csr_row_ptr,
                                  csr_col_ind,
                                  info);

        // Compute y = Ax
        rocsparse_scsrmv(handle,
                         rocsparse_operation_none,
                         m,
                         n,
                         nnz,
                         &alpha,
                         descr,
                         csr_val,
                         csr_row_ptr,
                         csr_col_ind,
                         info,
                         x,
                         &beta,
                         y);

        // Do more work
        // ...

        // Clean up
        rocsparse_destroy_mat_info(info);

  Note

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

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - trans – [in] matrix operation type.

    - m – [in] number of rows of the sparse CSR matrix.

    - n – [in] number of columns of the sparse CSR matrix.

    - nnz – [in] number of non-zero entries of the sparse CSR matrix.

    - alpha – [in] scalar \(\alpha\).

    - descr – [in] descriptor of the sparse CSR matrix. Currently, only rocsparse_matrix_type_general is supported.

    - csr_val – [in] array of `nnz` elements of the sparse CSR matrix.

    - csr_row_ptr – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix.

    - csr_col_ind – [in] array of `nnz` elements containing the column indices of the sparse CSR matrix.

    - info – [in] information collected by rocsparse_scsrmv_analysis(), rocsparse_dcsrmv_analysis(), rocsparse_ccsrmv_analysis() or rocsparse_dcsrmv_analysis(), can be `NULL` if no information is available.

    - x – [in] array of `n` elements ( \(op(A) == A\)) or `m` elements ( \(op(A) == A^T\) or \(op(A) == A^H\)).

    - beta – [in] scalar \(\beta\).

    - y – [inout] array of `m` elements ( \(op(A) == A\)) or `n` elements ( \(op(A) == A^T\) or \(op(A) == A^H\)).

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m`, `n` or `nnz` is invalid.

    - rocsparse_status_invalid_pointer – `descr`, `alpha`, `csr_val`, `csr_row_ptr`, `csr_col_ind`, `x`, `beta` or `y` pointer is invalid.

    - rocsparse_status_arch_mismatch – the device is not supported.

    - rocsparse_status_not_implemented – rocsparse_matrix_type != rocsparse_matrix_type_general.

### rocsparse_csrmv_analysis_clear()

rocsparse_status rocsparse_csrmv_clear(rocsparse_handle handle, rocsparse_mat_info info)

  Sparse matrix vector multiplication using CSR storage format.

  `rocsparse_csrmv_clear` deallocates all memory that was allocated by rocsparse_scsrmv_analysis(), rocsparse_dcsrmv_analysis(), rocsparse_ccsrmv_analysis() or rocsparse_zcsrmv_analysis(). This is especially useful, if memory is an issue and the analysis data is not required anymore for further computation, e.g. when switching to another sparse matrix format.

  Note

  Calling `rocsparse_csrmv_clear` is optional. All allocated resources will be cleared, when the opaque rocsparse_mat_info struct is destroyed using rocsparse_destroy_mat_info().

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - info – [inout] structure that holds the information collected during analysis step.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_pointer – `info` pointer is invalid.

    - rocsparse_status_memory_error – the buffer for the gathered information could not be deallocated.

    - rocsparse_status_internal_error – an internal error occurred.

### rocsparse_csrsv_zero_pivot()

rocsparse_status rocsparse_csrsv_zero_pivot(rocsparse_handle handle, const rocsparse_mat_descr descr, rocsparse_mat_info info, rocsparse_int *position)

  Sparse triangular solve using CSR storage format.

  `rocsparse_csrsv_zero_pivot` returns rocsparse_status_zero_pivot, if either a structural or numerical zero has been found during rocsparse_scsrsv_solve(), rocsparse_dcsrsv_solve(), rocsparse_ccsrsv_solve() or rocsparse_zcsrsv_solve() computation. The first zero pivot \(j\) at \(A_{j,j}\) is stored in `position`, using same index base as the CSR matrix.

  `position` can be in host or device memory. If no zero pivot has been found, `position` is set to -1 and rocsparse_status_success is returned instead.

  Note

  `rocsparse_csrsv_zero_pivot` is a blocking function. It might influence performance negatively.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - descr – [in] descriptor of the sparse CSR matrix.

    - info – [in] structure that holds the information collected during the analysis step.

    - position – [inout] pointer to zero pivot \(j\), can be in host or device memory.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_pointer – `info` or `position` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

    - rocsparse_status_zero_pivot – zero pivot has been found.

### rocsparse_csrsv_buffer_size()

rocsparse_status rocsparse_scsrsv_buffer_size(rocsparse_handle handle, rocsparse_operation trans, rocsparse_int m, rocsparse_int nnz, const rocsparse_mat_descr descr, const float *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, size_t *buffer_size)

rocsparse_status rocsparse_dcsrsv_buffer_size(rocsparse_handle handle, rocsparse_operation trans, rocsparse_int m, rocsparse_int nnz, const rocsparse_mat_descr descr, const double *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, size_t *buffer_size)

rocsparse_status rocsparse_ccsrsv_buffer_size(rocsparse_handle handle, rocsparse_operation trans, rocsparse_int m, rocsparse_int nnz, const rocsparse_mat_descr descr, const rocsparse_float_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, size_t *buffer_size)

rocsparse_status rocsparse_zcsrsv_buffer_size(rocsparse_handle handle, rocsparse_operation trans, rocsparse_int m, rocsparse_int nnz, const rocsparse_mat_descr descr, const rocsparse_double_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, size_t *buffer_size)

  Sparse triangular solve using CSR storage format.

  `rocsparse_csrsv_buffer_size` returns the size of the temporary storage buffer that is required by rocsparse_scsrsv_analysis(), rocsparse_dcsrsv_analysis(), rocsparse_ccsrsv_analysis(), rocsparse_zcsrsv_analysis(), rocsparse_scsrsv_solve(), rocsparse_dcsrsv_solve(), rocsparse_ccsrsv_solve() and rocsparse_zcsrsv_solve(). The temporary storage buffer must be allocated by the user. The size of the temporary storage buffer is identical to the size returned by rocsparse_scsrilu0_buffer_size(), rocsparse_dcsrilu0_buffer_size(), rocsparse_ccsrilu0_buffer_size() and rocsparse_zcsrilu0_buffer_size() if the matrix sparsity pattern is identical. The user allocated buffer can thus be shared between subsequent calls to those functions.

  Note

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

  Note

  This routine supports execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - trans – [in] matrix operation type.

    - m – [in] number of rows of the sparse CSR matrix.

    - nnz – [in] number of non-zero entries of the sparse CSR matrix.

    - descr – [in] descriptor of the sparse CSR matrix.

    - csr_val – [in] array of `nnz` elements of the sparse CSR matrix.

    - csr_row_ptr – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix.

    - csr_col_ind – [in] array of `nnz` elements containing the column indices of the sparse CSR matrix.

    - info – [out] structure that holds the information collected during the analysis step.

    - buffer_size – [out] number of bytes of the temporary storage buffer required by rocsparse_scsrsv_analysis(), rocsparse_dcsrsv_analysis(), rocsparse_ccsrsv_analysis(), rocsparse_zcsrsv_analysis(), rocsparse_scsrsv_solve(), rocsparse_dcsrsv_solve(), rocsparse_ccsrsv_solve() and rocsparse_zcsrsv_solve().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m` or `nnz` is invalid.

    - rocsparse_status_invalid_pointer – `descr`, `csr_val`, `csr_row_ptr`, `csr_col_ind`, `info` or `buffer_size` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

    - rocsparse_status_not_implemented – `trans` == rocsparse_operation_conjugate_transpose or rocsparse_matrix_type != rocsparse_matrix_type_general.

### rocsparse_csrsv_analysis()

rocsparse_status rocsparse_scsrsv_analysis(rocsparse_handle handle, rocsparse_operation trans, rocsparse_int m, rocsparse_int nnz, const rocsparse_mat_descr descr, const float *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, rocsparse_analysis_policy analysis, rocsparse_solve_policy solve, void *temp_buffer)

rocsparse_status rocsparse_dcsrsv_analysis(rocsparse_handle handle, rocsparse_operation trans, rocsparse_int m, rocsparse_int nnz, const rocsparse_mat_descr descr, const double *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, rocsparse_analysis_policy analysis, rocsparse_solve_policy solve, void *temp_buffer)

rocsparse_status rocsparse_ccsrsv_analysis(rocsparse_handle handle, rocsparse_operation trans, rocsparse_int m, rocsparse_int nnz, const rocsparse_mat_descr descr, const rocsparse_float_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, rocsparse_analysis_policy analysis, rocsparse_solve_policy solve, void *temp_buffer)

rocsparse_status rocsparse_zcsrsv_analysis(rocsparse_handle handle, rocsparse_operation trans, rocsparse_int m, rocsparse_int nnz, const rocsparse_mat_descr descr, const rocsparse_double_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, rocsparse_analysis_policy analysis, rocsparse_solve_policy solve, void *temp_buffer)

  Sparse triangular solve using CSR storage format.

  `rocsparse_csrsv_analysis` performs the analysis step for rocsparse_scsrsv_solve(), rocsparse_dcsrsv_solve(), rocsparse_ccsrsv_solve() and rocsparse_zcsrsv_solve(). It is expected that this function will be executed only once for a given matrix and particular operation type. The analysis meta data can be cleared by rocsparse_csrsv_clear().

  `rocsparse_csrsv_analysis` can share its meta data with rocsparse_scsrsm_analysis(), rocsparse_dcsrsm_analysis(), rocsparse_ccsrsm_analysis(), rocsparse_zcsrsm_analysis(), rocsparse_scsrilu0_analysis(), rocsparse_dcsrilu0_analysis(), rocsparse_ccsrilu0_analysis(), rocsparse_zcsrilu0_analysis(), rocsparse_scsric0_analysis(), rocsparse_dcsric0_analysis(), rocsparse_ccsric0_analysis() and rocsparse_zcsric0_analysis(). Selecting rocsparse_analysis_policy_reuse policy can greatly improve computation performance of meta data. However, the user need to make sure that the sparsity pattern remains unchanged. If this cannot be assured, rocsparse_analysis_policy_force has to be used.

  Note

  If the matrix sparsity pattern changes, the gathered information will become invalid.

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - trans – [in] matrix operation type.

    - m – [in] number of rows of the sparse CSR matrix.

    - nnz – [in] number of non-zero entries of the sparse CSR matrix.

    - descr – [in] descriptor of the sparse CSR matrix.

    - csr_val – [in] array of `nnz` elements of the sparse CSR matrix.

    - csr_row_ptr – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix.

    - csr_col_ind – [in] array of `nnz` elements containing the column indices of the sparse CSR matrix.

    - info – [out] structure that holds the information collected during the analysis step.

    - analysis – [in] rocsparse_analysis_policy_reuse or rocsparse_analysis_policy_force.

    - solve – [in] rocsparse_solve_policy_auto.

    - temp_buffer – [in] temporary storage buffer allocated by the user.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m` or `nnz` is invalid.

    - rocsparse_status_invalid_pointer – `descr`, `csr_row_ptr`, `csr_col_ind`, `info` or `temp_buffer` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

    - rocsparse_status_not_implemented – `trans` == rocsparse_operation_conjugate_transpose or rocsparse_matrix_type != rocsparse_matrix_type_general.

### rocsparse_csrsv_solve()

rocsparse_status rocsparse_scsrsv_solve(rocsparse_handle handle, rocsparse_operation trans, rocsparse_int m, rocsparse_int nnz, const float *alpha, const rocsparse_mat_descr descr, const float *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, const float *x, float *y, rocsparse_solve_policy policy, void *temp_buffer)

rocsparse_status rocsparse_dcsrsv_solve(rocsparse_handle handle, rocsparse_operation trans, rocsparse_int m, rocsparse_int nnz, const double *alpha, const rocsparse_mat_descr descr, const double *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, const double *x, double *y, rocsparse_solve_policy policy, void *temp_buffer)

rocsparse_status rocsparse_ccsrsv_solve(rocsparse_handle handle, rocsparse_operation trans, rocsparse_int m, rocsparse_int nnz, const rocsparse_float_complex *alpha, const rocsparse_mat_descr descr, const rocsparse_float_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, const rocsparse_float_complex *x, rocsparse_float_complex *y, rocsparse_solve_policy policy, void *temp_buffer)

rocsparse_status rocsparse_zcsrsv_solve(rocsparse_handle handle, rocsparse_operation trans, rocsparse_int m, rocsparse_int nnz, const rocsparse_double_complex *alpha, const rocsparse_mat_descr descr, const rocsparse_double_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, const rocsparse_double_complex *x, rocsparse_double_complex *y, rocsparse_solve_policy policy, void *temp_buffer)

  Sparse triangular solve using CSR storage format.

  `rocsparse_csrsv_solve` solves a sparse triangular linear system of a sparse \(m \times m\) matrix, defined in CSR storage format, a dense solution vector \(y\) and the right-hand side \(x\) that is multiplied by \(\alpha\), such that

  \[ op(A) \cdot y = \alpha \cdot x, \]
  with
  \[\begin{split} op(A) = \left\{ \begin{array}{ll} A, & \text{if trans == rocsparse_operation_none} \\ A^T, & \text{if trans == rocsparse_operation_transpose} \\ A^H, & \text{if trans == rocsparse_operation_conjugate_transpose} \end{array} \right. \end{split}\]

  `rocsparse_csrsv_solve` requires a user allocated temporary buffer. Its size is returned by rocsparse_scsrsv_buffer_size(), rocsparse_dcsrsv_buffer_size(), rocsparse_ccsrsv_buffer_size() or rocsparse_zcsrsv_buffer_size(). Furthermore, analysis meta data is required. It can be obtained by rocsparse_scsrsv_analysis(), rocsparse_dcsrsv_analysis(), rocsparse_ccsrsv_analysis() or rocsparse_zcsrsv_analysis(). `rocsparse_csrsv_solve` reports the first zero pivot (either numerical or structural zero). The zero pivot status can be checked calling rocsparse_csrsv_zero_pivot(). If rocsparse_diag_type == rocsparse_diag_type_unit, no zero pivot will be reported, even if \(A_{j,j} = 0\) for some \(j\).

  Example

    Consider the lower triangular \(m \times m\) matrix \(L\), stored in CSR storage format with unit diagonal. The following example solves \(L \cdot y = x\).

        // Create rocSPARSE handle
        rocsparse_handle handle;
        rocsparse_create_handle(&handle);

        // Create matrix descriptor
        rocsparse_mat_descr descr;
        rocsparse_create_mat_descr(&descr);
        rocsparse_set_mat_fill_mode(descr, rocsparse_fill_mode_lower);
        rocsparse_set_mat_diag_type(descr, rocsparse_diag_type_unit);

        // Create matrix info structure
        rocsparse_mat_info info;
        rocsparse_create_mat_info(&info);

        // Obtain required buffer size
        size_t buffer_size;
        rocsparse_dcsrsv_buffer_size(handle,
                                     rocsparse_operation_none,
                                     m,
                                     nnz,
                                     descr,
                                     csr_val,
                                     csr_row_ptr,
                                     csr_col_ind,
                                     info,
                                     &buffer_size);

        // Allocate temporary buffer
        void* temp_buffer;
        hipMalloc(&temp_buffer, buffer_size);

        // Perform analysis step
        rocsparse_dcsrsv_analysis(handle,
                                  rocsparse_operation_none,
                                  m,
                                  nnz,
                                  descr,
                                  csr_val,
                                  csr_row_ptr,
                                  csr_col_ind,
                                  info,
                                  rocsparse_analysis_policy_reuse,
                                  rocsparse_solve_policy_auto,
                                  temp_buffer);

        // Solve Ly = x
        rocsparse_dcsrsv_solve(handle,
                               rocsparse_operation_none,
                               m,
                               nnz,
                               &alpha,
                               descr,
                               csr_val,
                               csr_row_ptr,
                               csr_col_ind,
                               info,
                               x,
                               y,
                               rocsparse_solve_policy_auto,
                               temp_buffer);

        // No zero pivot should be found, with L having unit diagonal

        // Clean up
        hipFree(temp_buffer);
        rocsparse_destroy_mat_info(info);
        rocsparse_destroy_mat_descr(descr);
        rocsparse_destroy_handle(handle);

  Note

  The sparse CSR matrix has to be sorted. This can be achieved by calling rocsparse_csrsort().

  Note

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

  Note

  Currently, only `trans` == rocsparse_operation_none and `trans` == rocsparse_operation_transpose is supported.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - trans – [in] matrix operation type.

    - m – [in] number of rows of the sparse CSR matrix.

    - nnz – [in] number of non-zero entries of the sparse CSR matrix.

    - alpha – [in] scalar \(\alpha\).

    - descr – [in] descriptor of the sparse CSR matrix.

    - csr_val – [in] array of `nnz` elements of the sparse CSR matrix.

    - csr_row_ptr – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix.

    - csr_col_ind – [in] array of `nnz` elements containing the column indices of the sparse CSR matrix.

    - info – [in] structure that holds the information collected during the analysis step.

    - x – [in] array of `m` elements, holding the right-hand side.

    - y – [out] array of `m` elements, holding the solution.

    - policy – [in] rocsparse_solve_policy_auto.

    - temp_buffer – [in] temporary storage buffer allocated by the user.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m` or `nnz` is invalid.

    - rocsparse_status_invalid_pointer – `descr`, `alpha`, `csr_val`, `csr_row_ptr`, `csr_col_ind`, `x` or `y` pointer is invalid.

    - rocsparse_status_arch_mismatch – the device is not supported.

    - rocsparse_status_internal_error – an internal error occurred.

    - rocsparse_status_not_implemented – `trans` == rocsparse_operation_conjugate_transpose or rocsparse_matrix_type != rocsparse_matrix_type_general.

### rocsparse_csrsv_clear()

rocsparse_status rocsparse_csrsv_clear(rocsparse_handle handle, const rocsparse_mat_descr descr, rocsparse_mat_info info)

  Sparse triangular solve using CSR storage format.

  `rocsparse_csrsv_clear` deallocates all memory that was allocated by rocsparse_scsrsv_analysis(), rocsparse_dcsrsv_analysis(), rocsparse_ccsrsv_analysis() or rocsparse_zcsrsv_analysis(). This is especially useful, if memory is an issue and the analysis data is not required for further computation, e.g. when switching to another sparse matrix format. Calling `rocsparse_csrsv_clear` is optional. All allocated resources will be cleared, when the opaque rocsparse_mat_info struct is destroyed using rocsparse_destroy_mat_info().

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - descr – [in] descriptor of the sparse CSR matrix.

    - info – [inout] structure that holds the information collected during the analysis step.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_pointer – `info` pointer is invalid.

    - rocsparse_status_memory_error – the buffer holding the meta data could not be deallocated.

    - rocsparse_status_internal_error – an internal error occurred.

### rocsparse_csritsv_zero_pivot()

rocsparse_status rocsparse_csritsv_zero_pivot(rocsparse_handle handle, const rocsparse_mat_descr descr, rocsparse_mat_info info, rocsparse_int *position)

  Sparse iterative triangular solve using CSR storage format.

  `rocsparse_csritsv_zero_pivot` returns rocsparse_status_zero_pivot, if either a structural or numerical zero has been found during rocsparse_csritsv_solve() and or rocsparse_csritsv_analysis(), execution. The first zero pivot \(j\) at \(A_{j,j}\) is stored in `position`, using same index base as the CSR matrix.

  `position` can be in host or device memory. If no zero pivot has been found, `position` is set to -1 and rocsparse_status_success is returned instead.

  Note

  `rocsparse_csritsv_zero_pivot` is a blocking function. It might influence performance negatively.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - descr – [in] descriptor of the sparse CSR matrix.

    - info – [in] structure that holds the information collected during the analysis step.

    - position – [inout] pointer to zero pivot \(j\), can be in host or device memory.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_pointer – `info` or `position` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

    - rocsparse_status_zero_pivot – zero pivot has been found.

### rocsparse_csritsv_buffer_size()

rocsparse_status rocsparse_scsritsv_buffer_size(rocsparse_handle handle, rocsparse_operation trans, rocsparse_int m, rocsparse_int nnz, const rocsparse_mat_descr descr, const float *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, size_t *buffer_size)

rocsparse_status rocsparse_dcsritsv_buffer_size(rocsparse_handle handle, rocsparse_operation trans, rocsparse_int m, rocsparse_int nnz, const rocsparse_mat_descr descr, const double *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, size_t *buffer_size)

rocsparse_status rocsparse_ccsritsv_buffer_size(rocsparse_handle handle, rocsparse_operation trans, rocsparse_int m, rocsparse_int nnz, const rocsparse_mat_descr descr, const rocsparse_float_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, size_t *buffer_size)

rocsparse_status rocsparse_zcsritsv_buffer_size(rocsparse_handle handle, rocsparse_operation trans, rocsparse_int m, rocsparse_int nnz, const rocsparse_mat_descr descr, const rocsparse_double_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, size_t *buffer_size)

  Sparse iterative triangular solve using CSR storage format.

  `rocsparse_csritsv_buffer_size` returns the size of the temporary storage buffer that is required by rocsparse_scsritsv_analysis(), rocsparse_dcsritsv_analysis(), rocsparse_ccsritsv_analysis(), rocsparse_zcsritsv_analysis(), rocsparse_scsritsv_solve(), rocsparse_dcsritsv_solve(), rocsparse_ccsritsv_solve() and rocsparse_zcsritsv_solve(). The temporary storage buffer must be allocated by the user.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - trans – [in] matrix operation type.

    - m – [in] number of rows of the sparse CSR matrix.

    - nnz – [in] number of non-zero entries of the sparse CSR matrix.

    - descr – [in] descriptor of the sparse CSR matrix.

    - csr_val – [in] array of `nnz` elements of the sparse CSR matrix.

    - csr_row_ptr – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix.

    - csr_col_ind – [in] array of `nnz` elements containing the column indices of the sparse CSR matrix.

    - info – [out] structure that holds the information collected during the analysis step.

    - buffer_size – [out] number of bytes of the temporary storage buffer required by rocsparse_scsritsv_analysis(), rocsparse_dcsritsv_analysis(), rocsparse_ccsritsv_analysis(), rocsparse_zcsritsv_analysis(), rocsparse_scsritsv_solve(), rocsparse_dcsritsv_solve(), rocsparse_ccsritsv_solve() and rocsparse_zcsritsv_solve().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m` or `nnz` is invalid.

    - rocsparse_status_invalid_pointer – `descr`, `csr_val`, `csr_row_ptr`, `csr_col_ind`, `info` or `buffer_size` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

    - rocsparse_status_not_implemented – rocsparse_matrix_type != rocsparse_matrix_type_general and rocsparse_matrix_type != rocsparse_matrix_type_triangular.

### rocsparse_csritsv_analysis()

rocsparse_status rocsparse_scsritsv_analysis(rocsparse_handle handle, rocsparse_operation trans, rocsparse_int m, rocsparse_int nnz, const rocsparse_mat_descr descr, const float *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, rocsparse_analysis_policy analysis, rocsparse_solve_policy solve, void *temp_buffer)

rocsparse_status rocsparse_dcsritsv_analysis(rocsparse_handle handle, rocsparse_operation trans, rocsparse_int m, rocsparse_int nnz, const rocsparse_mat_descr descr, const double *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, rocsparse_analysis_policy analysis, rocsparse_solve_policy solve, void *temp_buffer)

rocsparse_status rocsparse_ccsritsv_analysis(rocsparse_handle handle, rocsparse_operation trans, rocsparse_int m, rocsparse_int nnz, const rocsparse_mat_descr descr, const rocsparse_float_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, rocsparse_analysis_policy analysis, rocsparse_solve_policy solve, void *temp_buffer)

rocsparse_status rocsparse_zcsritsv_analysis(rocsparse_handle handle, rocsparse_operation trans, rocsparse_int m, rocsparse_int nnz, const rocsparse_mat_descr descr, const rocsparse_double_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, rocsparse_analysis_policy analysis, rocsparse_solve_policy solve, void *temp_buffer)

  Sparse iterative triangular solve using CSR storage format.

  `rocsparse_csritsv_analysis` performs the analysis step for rocsparse_scsritsv_solve(), rocsparse_dcsritsv_solve(), rocsparse_ccsritsv_solve() and rocsparse_zcsritsv_solve(). It is expected that this function will be executed only once for a given matrix and particular operation type. The analysis meta data can be cleared by rocsparse_csritsv_clear().

  Selecting rocsparse_analysis_policy_reuse policy can greatly improve computation performance of meta data. However, the user need to make sure that the sparsity pattern remains unchanged. If this cannot be assured, rocsparse_analysis_policy_force has to be used.

  Note

  If the matrix sparsity pattern changes, the gathered information will become invalid.

  Note

  This function is blocking with respect to the host.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - trans – [in] matrix operation type.

    - m – [in] number of rows of the sparse CSR matrix.

    - nnz – [in] number of non-zero entries of the sparse CSR matrix.

    - descr – [in] descriptor of the sparse CSR matrix.

    - csr_val – [in] array of `nnz` elements of the sparse CSR matrix.

    - csr_row_ptr – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix.

    - csr_col_ind – [in] array of `nnz` elements containing the column indices of the sparse CSR matrix.

    - info – [out] structure that holds the information collected during the analysis step.

    - analysis – [in] rocsparse_analysis_policy_reuse or rocsparse_analysis_policy_force.

    - solve – [in] rocsparse_solve_policy_auto.

    - temp_buffer – [in] temporary storage buffer allocated by the user.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m` or `nnz` is invalid.

    - rocsparse_status_invalid_pointer – `descr`, `csr_row_ptr`, `csr_col_ind`, `info` or `temp_buffer` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

    - rocsparse_status_not_implemented – rocsparse_matrix_type != rocsparse_matrix_type_general and rocsparse_matrix_type != rocsparse_matrix_type_triangular.

### rocsparse_csritsv_solve()

rocsparse_status rocsparse_scsritsv_solve(rocsparse_handle handle, rocsparse_int *host_nmaxiter, const float *host_tol, float *host_history, rocsparse_operation trans, rocsparse_int m, rocsparse_int nnz, const float *alpha, const rocsparse_mat_descr descr, const float *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, const float *x, float *y, rocsparse_solve_policy policy, void *temp_buffer)

rocsparse_status rocsparse_dcsritsv_solve(rocsparse_handle handle, rocsparse_int *host_nmaxiter, const double *host_tol, double *host_history, rocsparse_operation trans, rocsparse_int m, rocsparse_int nnz, const double *alpha, const rocsparse_mat_descr descr, const double *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, const double *x, double *y, rocsparse_solve_policy policy, void *temp_buffer)

rocsparse_status rocsparse_ccsritsv_solve(rocsparse_handle handle, rocsparse_int *host_nmaxiter, const float *host_tol, float *host_history, rocsparse_operation trans, rocsparse_int m, rocsparse_int nnz, const rocsparse_float_complex *alpha, const rocsparse_mat_descr descr, const rocsparse_float_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, const rocsparse_float_complex *x, rocsparse_float_complex *y, rocsparse_solve_policy policy, void *temp_buffer)

rocsparse_status rocsparse_zcsritsv_solve(rocsparse_handle handle, rocsparse_int *host_nmaxiter, const double *host_tol, double *host_history, rocsparse_operation trans, rocsparse_int m, rocsparse_int nnz, const rocsparse_double_complex *alpha, const rocsparse_mat_descr descr, const rocsparse_double_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, const rocsparse_double_complex *x, rocsparse_double_complex *y, rocsparse_solve_policy policy, void *temp_buffer)

  Sparse iterative triangular solve using CSR storage format.

  `rocsparse_csritsv_solve` solves iteratively with the use of the Jacobi method a sparse triangular linear system of a sparse \(m \times m\) matrix, defined in CSR storage format, a dense solution vector \(y\) and the right-hand side \(x\) that is multiplied by \(\alpha\), such that

  \[ op(A) \cdot y = \alpha \cdot x, \]
  with
  \[\begin{split} op(A) = \left\{ \begin{array}{ll} A, & \text{if trans == rocsparse_operation_none} \\ A^T, & \text{if trans == rocsparse_operation_transpose} \\ A^H, & \text{if trans == rocsparse_operation_conjugate_transpose} \end{array} \right. \end{split}\]

  `rocsparse_csritsv_solve` requires a user allocated temporary buffer. Its size is returned by rocsparse_scsritsv_buffer_size(), rocsparse_dcsritsv_buffer_size(), rocsparse_ccsritsv_buffer_size() or rocsparse_zcsritsv_buffer_size(). Furthermore, analysis meta data is required. It can be obtained by rocsparse_scsritsv_analysis(), rocsparse_dcsritsv_analysis(), rocsparse_ccsritsv_analysis() or rocsparse_zcsritsv_analysis(). `rocsparse_csritsv_solve` reports the first zero pivot (either numerical or structural zero). The zero pivot status can be checked calling rocsparse_csritsv_zero_pivot(). If rocsparse_diag_type == rocsparse_diag_type_unit, no zero pivot will be reported, even if \(A_{j,j} = 0\) for some \(j\).

  Example

    Consider the lower triangular \(m \times m\) matrix \(L\), stored in CSR storage format with unit diagonal. The following example solves \(L \cdot y = x\).

        // Create rocSPARSE handle
        rocsparse_handle handle;
        rocsparse_create_handle(&handle);

        // Create matrix descriptor
        rocsparse_mat_descr descr;
        rocsparse_create_mat_descr(&descr);
        rocsparse_set_mat_fill_mode(descr, rocsparse_fill_mode_lower);
        rocsparse_set_mat_diag_type(descr, rocsparse_diag_type_unit);

        // Create matrix info structure
        rocsparse_mat_info info;
        rocsparse_create_mat_info(&info);

        // Obtain required buffer size
        size_t buffer_size;
        rocsparse_dcsritsv_buffer_size(handle,
                                     rocsparse_operation_none,
                                     m,
                                     nnz,
                                     descr,
                                     csr_val,
                                     csr_row_ptr,
                                     csr_col_ind,
                                     info,
                                     &buffer_size);

        // Allocate temporary buffer
        void* temp_buffer;
        hipMalloc(&temp_buffer, buffer_size);

        // Perform analysis step
        rocsparse_dcsritsv_analysis(handle,
                                  rocsparse_operation_none,
                                  m,
                                  nnz,
                                  descr,
                                  csr_val,
                                  csr_row_ptr,
                                  csr_col_ind,
                                  info,
                                  rocsparse_analysis_policy_reuse,
                                  rocsparse_solve_policy_auto,
                                  temp_buffer);

        // Solve Ly = x
        rocsparse_int nmaxiter = 200;
        rocsparse_int maxiter = nmaxiter;
        tol = 1.0e-4;
        history[200];
        rocsparse_dcsritsv_solve(handle,
                               &maxiter,
                               &tol,
                               history,
                               rocsparse_operation_none,
                               m,
                               nnz,
                               &alpha,
                               descr,
                               csr_val,
                               csr_row_ptr,
                               csr_col_ind,
                               info,
                               x,
                               y,
                               rocsparse_solve_policy_auto,
                               temp_buffer);

        if (maxiter < nmaxiter) {} // convergence
        else {} // non converged
        for (int i=0;i<maxiter;++i) printf("iter = %d, max residual=%e\n", iter, history[i]);
        // No zero pivot should be found, with L having unit diagonal

        // Clean up
        hipFree(temp_buffer);
        rocsparse_destroy_mat_info(info);
        rocsparse_destroy_mat_descr(descr);
        rocsparse_destroy_handle(handle);

  Note

  The sparse CSR matrix has to be sorted. This can be achieved by calling rocsparse_csrsort().

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - host_nmaxiter – [inout] maximum number of iteration on input and maximum number of iteration on output.

    - host_tol – [in] if the pointer is null then loop will execute `nmaxiter`[0] iterations.

    - host_history – [out] (optional, record history)

    - trans – [in] matrix operation type.

    - m – [in] number of rows of the sparse CSR matrix.

    - nnz – [in] number of non-zero entries of the sparse CSR matrix.

    - alpha – [in] scalar \(\alpha\).

    - descr – [in] descriptor of the sparse CSR matrix.

    - csr_val – [in] array of `nnz` elements of the sparse CSR matrix.

    - csr_row_ptr – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix.

    - csr_col_ind – [in] array of `nnz` elements containing the column indices of the sparse CSR matrix.

    - info – [in] structure that holds the information collected during the analysis step.

    - x – [in] array of `m` elements, holding the right-hand side.

    - y – [out] array of `m` elements, holding the solution.

    - policy – [in] rocsparse_solve_policy_auto.

    - temp_buffer – [in] temporary storage buffer allocated by the user.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m` or `nnz` is invalid.

    - rocsparse_status_invalid_pointer – `descr`, `alpha`, `csr_val`, `csr_row_ptr`, `csr_col_ind`, `x` or `y` pointer is invalid.

    - rocsparse_status_arch_mismatch – the device is not supported.

    - rocsparse_status_internal_error – an internal error occurred.

    - rocsparse_status_not_implemented – rocsparse_matrix_type != rocsparse_matrix_type_general and rocsparse_matrix_type != rocsparse_matrix_type_triangular.

### rocsparse_csritsv_clear()

rocsparse_status rocsparse_csritsv_clear(rocsparse_handle handle, const rocsparse_mat_descr descr, rocsparse_mat_info info)

  Sparse triangular solve using CSR storage format.

  `rocsparse_csritsv_clear` deallocates all memory that was allocated by rocsparse_scsritsv_analysis(), rocsparse_dcsritsv_analysis(), rocsparse_ccsritsv_analysis() or rocsparse_zcsritsv_analysis(). This is especially useful, if memory is an issue and the analysis data is not required for further computation, e.g. when switching to another sparse matrix format. Calling `rocsparse_csritsv_clear` is optional. All allocated resources will be cleared, when the opaque rocsparse_mat_info struct is destroyed using rocsparse_destroy_mat_info().

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - descr – [in] descriptor of the sparse CSR matrix.

    - info – [inout] structure that holds the information collected during the analysis step.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_pointer – `info` pointer is invalid.

    - rocsparse_status_memory_error – the buffer holding the meta data could not be deallocated.

    - rocsparse_status_internal_error – an internal error occurred.

### rocsparse_ellmv()

rocsparse_status rocsparse_sellmv(rocsparse_handle handle, rocsparse_operation trans, rocsparse_int m, rocsparse_int n, const float *alpha, const rocsparse_mat_descr descr, const float *ell_val, const rocsparse_int *ell_col_ind, rocsparse_int ell_width, const float *x, const float *beta, float *y)

rocsparse_status rocsparse_dellmv(rocsparse_handle handle, rocsparse_operation trans, rocsparse_int m, rocsparse_int n, const double *alpha, const rocsparse_mat_descr descr, const double *ell_val, const rocsparse_int *ell_col_ind, rocsparse_int ell_width, const double *x, const double *beta, double *y)

rocsparse_status rocsparse_cellmv(rocsparse_handle handle, rocsparse_operation trans, rocsparse_int m, rocsparse_int n, const rocsparse_float_complex *alpha, const rocsparse_mat_descr descr, const rocsparse_float_complex *ell_val, const rocsparse_int *ell_col_ind, rocsparse_int ell_width, const rocsparse_float_complex *x, const rocsparse_float_complex *beta, rocsparse_float_complex *y)

rocsparse_status rocsparse_zellmv(rocsparse_handle handle, rocsparse_operation trans, rocsparse_int m, rocsparse_int n, const rocsparse_double_complex *alpha, const rocsparse_mat_descr descr, const rocsparse_double_complex *ell_val, const rocsparse_int *ell_col_ind, rocsparse_int ell_width, const rocsparse_double_complex *x, const rocsparse_double_complex *beta, rocsparse_double_complex *y)

  Sparse matrix vector multiplication using ELL storage format.

  `rocsparse_ellmv` multiplies the scalar \(\alpha\) with a sparse \(m \times n\) matrix, defined in ELL storage format, and the dense vector \(x\) and adds the result to the dense vector \(y\) that is multiplied by the scalar \(\beta\), such that

  \[ y := \alpha \cdot op(A) \cdot x + \beta \cdot y, \]
  with
  \[\begin{split} op(A) = \left\{ \begin{array}{ll} A, & \text{if trans == rocsparse_operation_none} \\ A^T, & \text{if trans == rocsparse_operation_transpose} \\ A^H, & \text{if trans == rocsparse_operation_conjugate_transpose} \end{array} \right. \end{split}\]

      for(i = 0; i < m; ++i)
      {
          y[i] = beta * y[i];

          for(p = 0; p < ell_width; ++p)
          {
              idx = p * m + i;

              if((ell_col_ind[idx] >= 0) && (ell_col_ind[idx] < n))
              {
                  y[i] = y[i] + alpha * ell_val[idx] * x[ell_col_ind[idx]];
              }
          }
      }

  Note

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

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - trans – [in] matrix operation type.

    - m – [in] number of rows of the sparse ELL matrix.

    - n – [in] number of columns of the sparse ELL matrix.

    - alpha – [in] scalar \(\alpha\).

    - descr – [in] descriptor of the sparse ELL matrix. Currently, only rocsparse_matrix_type_general is supported.

    - ell_val – [in] array that contains the elements of the sparse ELL matrix. Padded elements should be zero.

    - ell_col_ind – [in] array that contains the column indices of the sparse ELL matrix. Padded column indices should be -1.

    - ell_width – [in] number of non-zero elements per row of the sparse ELL matrix.

    - x – [in] array of `n` elements ( \(op(A) == A\)) or `m` elements ( \(op(A) == A^T\) or \(op(A) == A^H\)).

    - beta – [in] scalar \(\beta\).

    - y – [inout] array of `m` elements ( \(op(A) == A\)) or `n` elements ( \(op(A) == A^T\) or \(op(A) == A^H\)).

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m`, `n` or `ell_width` is invalid.

    - rocsparse_status_invalid_pointer – `descr`, `alpha`, `ell_val`, `ell_col_ind`, `x`, `beta` or `y` pointer is invalid.

    - rocsparse_status_not_implemented – rocsparse_matrix_type != rocsparse_matrix_type_general.

### rocsparse_hybmv()

rocsparse_status rocsparse_shybmv(rocsparse_handle handle, rocsparse_operation trans, const float *alpha, const rocsparse_mat_descr descr, const rocsparse_hyb_mat hyb, const float *x, const float *beta, float *y)

rocsparse_status rocsparse_dhybmv(rocsparse_handle handle, rocsparse_operation trans, const double *alpha, const rocsparse_mat_descr descr, const rocsparse_hyb_mat hyb, const double *x, const double *beta, double *y)

rocsparse_status rocsparse_chybmv(rocsparse_handle handle, rocsparse_operation trans, const rocsparse_float_complex *alpha, const rocsparse_mat_descr descr, const rocsparse_hyb_mat hyb, const rocsparse_float_complex *x, const rocsparse_float_complex *beta, rocsparse_float_complex *y)

rocsparse_status rocsparse_zhybmv(rocsparse_handle handle, rocsparse_operation trans, const rocsparse_double_complex *alpha, const rocsparse_mat_descr descr, const rocsparse_hyb_mat hyb, const rocsparse_double_complex *x, const rocsparse_double_complex *beta, rocsparse_double_complex *y)

  Sparse matrix vector multiplication using HYB storage format.

  `rocsparse_hybmv` multiplies the scalar \(\alpha\) with a sparse \(m \times n\) matrix, defined in HYB storage format, and the dense vector \(x\) and adds the result to the dense vector \(y\) that is multiplied by the scalar \(\beta\), such that

  \[ y := \alpha \cdot op(A) \cdot x + \beta \cdot y, \]
  with
  \[\begin{split} op(A) = \left\{ \begin{array}{ll} A, & \text{if trans == rocsparse_operation_none} \\ A^T, & \text{if trans == rocsparse_operation_transpose} \\ A^H, & \text{if trans == rocsparse_operation_conjugate_transpose} \end{array} \right. \end{split}\]

  Note

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

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - trans – [in] matrix operation type.

    - alpha – [in] scalar \(\alpha\).

    - descr – [in] descriptor of the sparse HYB matrix. Currently, only rocsparse_matrix_type_general is supported.

    - hyb – [in] matrix in HYB storage format.

    - x – [in] array of `n` elements ( \(op(A) == A\)) or `m` elements ( \(op(A) == A^T\) or \(op(A) == A^H\)).

    - beta – [in] scalar \(\beta\).

    - y – [inout] array of `m` elements ( \(op(A) == A\)) or `n` elements ( \(op(A) == A^T\) or \(op(A) == A^H\)).

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `hyb` structure was not initialized with valid matrix sizes.

    - rocsparse_status_invalid_pointer – `descr`, `alpha`, `hyb`, `x`, `beta` or `y` pointer is invalid.

    - rocsparse_status_invalid_value – `hyb` structure was not initialized with a valid partitioning type.

    - rocsparse_status_arch_mismatch – the device is not supported.

    - rocsparse_status_memory_error – the buffer could not be allocated.

    - rocsparse_status_internal_error – an internal error occurred.

    - rocsparse_status_not_implemented – `trans` != rocsparse_operation_none or rocsparse_matrix_type != rocsparse_matrix_type_general.

### rocsparse_gebsrmv()

rocsparse_status rocsparse_sgebsrmv(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const float *alpha, const rocsparse_mat_descr descr, const float *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, const float *x, const float *beta, float *y)

rocsparse_status rocsparse_dgebsrmv(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const double *alpha, const rocsparse_mat_descr descr, const double *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, const double *x, const double *beta, double *y)

rocsparse_status rocsparse_cgebsrmv(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const rocsparse_float_complex *alpha, const rocsparse_mat_descr descr, const rocsparse_float_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, const rocsparse_float_complex *x, const rocsparse_float_complex *beta, rocsparse_float_complex *y)

rocsparse_status rocsparse_zgebsrmv(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const rocsparse_double_complex *alpha, const rocsparse_mat_descr descr, const rocsparse_double_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, const rocsparse_double_complex *x, const rocsparse_double_complex *beta, rocsparse_double_complex *y)

  Sparse matrix vector multiplication using GEBSR storage format.

  `rocsparse_gebsrmv` multiplies the scalar \(\alpha\) with a sparse \((mb \cdot \text{row_block_dim}) \times (nb \cdot \text{col_block_dim})\) matrix, defined in GEBSR storage format, and the dense vector \(x\) and adds the result to the dense vector \(y\) that is multiplied by the scalar \(\beta\), such that

  \[ y := \alpha \cdot op(A) \cdot x + \beta \cdot y, \]
  with
  \[\begin{split} op(A) = \left\{ \begin{array}{ll} A, & \text{if trans == rocsparse_operation_none} \\ A^T, & \text{if trans == rocsparse_operation_transpose} \\ A^H, & \text{if trans == rocsparse_operation_conjugate_transpose} \end{array} \right. \end{split}\]

  Note

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

  Note

  Currently, only `trans` == rocsparse_operation_none is supported.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - dir – [in] matrix storage of GEBSR blocks.

    - trans – [in] matrix operation type.

    - mb – [in] number of block rows of the sparse GEBSR matrix.

    - nb – [in] number of block columns of the sparse GEBSR matrix.

    - nnzb – [in] number of non-zero blocks of the sparse GEBSR matrix.

    - alpha – [in] scalar \(\alpha\).

    - descr – [in] descriptor of the sparse GEBSR matrix. Currently, only rocsparse_matrix_type_general is supported.

    - bsr_val – [in] array of `nnzb` blocks of the sparse GEBSR matrix.

    - bsr_row_ptr – [in] array of `mb+1` elements that point to the start of every block row of the sparse GEBSR matrix.

    - bsr_col_ind – [in] array of `nnz` containing the block column indices of the sparse GEBSR matrix.

    - row_block_dim – [in] row block dimension of the sparse GEBSR matrix.

    - col_block_dim – [in] column block dimension of the sparse GEBSR matrix.

    - x – [in] array of `nb*col_block_dim` elements ( \(op(A) = A\)) or `mb*row_block_dim` elements ( \(op(A) = A^T\) or \(op(A) = A^H\)).

    - beta – [in] scalar \(\beta\).

    - y – [inout] array of `mb*row_block_dim` elements ( \(op(A) = A\)) or `nb*col_block_dim` elements ( \(op(A) = A^T\) or \(op(A) = A^H\)).

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `mb`, `nb`, `nnzb`, `row_block_dim` or `col_block_dim` is invalid.

    - rocsparse_status_invalid_pointer – `descr`, `alpha`, `bsr_val`, `bsr_row_ind`, `bsr_col_ind`, `x`, `beta` or `y` pointer is invalid.

    - rocsparse_status_arch_mismatch – the device is not supported.

    - rocsparse_status_not_implemented – `trans` != rocsparse_operation_none or rocsparse_matrix_type != rocsparse_matrix_type_general.

### rocsparse_gemvi_buffer_size()

rocsparse_status rocsparse_sgemvi_buffer_size(rocsparse_handle handle, rocsparse_operation trans, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, size_t *buffer_size)

rocsparse_status rocsparse_dgemvi_buffer_size(rocsparse_handle handle, rocsparse_operation trans, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, size_t *buffer_size)

rocsparse_status rocsparse_cgemvi_buffer_size(rocsparse_handle handle, rocsparse_operation trans, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, size_t *buffer_size)

rocsparse_status rocsparse_zgemvi_buffer_size(rocsparse_handle handle, rocsparse_operation trans, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, size_t *buffer_size)

  Dense matrix sparse vector multiplication.

  `rocsparse_gemvi_buffer_size` returns the size of the temporary storage buffer required by rocsparse_sgemvi(), rocsparse_dgemvi(), rocsparse_cgemvi() or rocsparse_zgemvi(). The temporary storage buffer must be allocated by the user.

  Note

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

  Note

  This routine supports execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - trans – [in] matrix operation type.

    - m – [in] number of rows of the dense matrix.

    - n – [in] number of columns of the dense matrix.

    - nnz – [in] number of non-zero entries in the sparse vector.

    - buffer_size – [out] temporary storage buffer size.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m`, `n`, or `nnz` is invalid.

    - rocsparse_status_invalid_pointer – `buffer_size` pointer is invalid.

    - rocsparse_status_not_implemented – `trans` != rocsparse_operation_none or rocsparse_matrix_type != rocsparse_matrix_type_general.

### rocsparse_gemvi()

rocsparse_status rocsparse_sgemvi(rocsparse_handle handle, rocsparse_operation trans, rocsparse_int m, rocsparse_int n, const float *alpha, const float *A, rocsparse_int lda, rocsparse_int nnz, const float *x_val, const rocsparse_int *x_ind, const float *beta, float *y, rocsparse_index_base idx_base, void *temp_buffer)

rocsparse_status rocsparse_dgemvi(rocsparse_handle handle, rocsparse_operation trans, rocsparse_int m, rocsparse_int n, const double *alpha, const double *A, rocsparse_int lda, rocsparse_int nnz, const double *x_val, const rocsparse_int *x_ind, const double *beta, double *y, rocsparse_index_base idx_base, void *temp_buffer)

rocsparse_status rocsparse_cgemvi(rocsparse_handle handle, rocsparse_operation trans, rocsparse_int m, rocsparse_int n, const rocsparse_float_complex *alpha, const rocsparse_float_complex *A, rocsparse_int lda, rocsparse_int nnz, const rocsparse_float_complex *x_val, const rocsparse_int *x_ind, const rocsparse_float_complex *beta, rocsparse_float_complex *y, rocsparse_index_base idx_base, void *temp_buffer)

rocsparse_status rocsparse_zgemvi(rocsparse_handle handle, rocsparse_operation trans, rocsparse_int m, rocsparse_int n, const rocsparse_double_complex *alpha, const rocsparse_double_complex *A, rocsparse_int lda, rocsparse_int nnz, const rocsparse_double_complex *x_val, const rocsparse_int *x_ind, const rocsparse_double_complex *beta, rocsparse_double_complex *y, rocsparse_index_base idx_base, void *temp_buffer)

  Dense matrix sparse vector multiplication.

  `rocsparse_gemvi` multiplies the scalar \(\alpha\) with a dense \(m \times n\) matrix \(A\) and the sparse vector \(x\) and adds the result to the dense vector \(y\) that is multiplied by the scalar \(\beta\), such that

  \[ y := \alpha \cdot op(A) \cdot x + \beta \cdot y, \]
  with
  \[\begin{split} op(A) = \left\{ \begin{array}{ll} A, & \text{if trans == rocsparse_operation_none} \\ A^T, & \text{if trans == rocsparse_operation_transpose} \\ A^H, & \text{if trans == rocsparse_operation_conjugate_transpose} \end{array} \right. \end{split}\]

  `rocsparse_gemvi` requires a user allocated temporary buffer. Its size is returned by rocsparse_sgemvi_buffer_size(), rocsparse_dgemvi_buffer_size(), rocsparse_cgemvi_buffer_size() or rocsparse_zgemvi_buffer_size().

  Note

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

  Note

  Currently, only `trans` == rocsparse_operation_none is supported.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - trans – [in] matrix operation type.

    - m – [in] number of rows of the dense matrix.

    - n – [in] number of columns of the dense matrix.

    - alpha – [in] scalar \(\alpha\).

    - A – [in] pointer to the dense matrix.

    - lda – [in] leading dimension of the dense matrix

    - nnz – [in] number of non-zero entries in the sparse vector

    - x_val – [in] array of `nnz` elements containing the values of the sparse vector

    - x_ind – [in] array of `nnz` elements containing the indices of the sparse vector

    - beta – [in] scalar \(\beta\).

    - y – [inout] array of `m` elements ( \(op(A) == A\)) or `n` elements ( \(op(A) == A^T\) or \(op(A) == A^H\)).

    - idx_base – [in] rocsparse_index_base_zero or rocsparse_index_base_one.

    - temp_buffer – [in] temporary storage buffer

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m`, `n`, `lda` or `nnz` is invalid.

    - rocsparse_status_invalid_pointer – `alpha`, `A`, `x_val`, `x_ind`, `beta`, `y` or `temp_buffer` pointer is invalid.

    - rocsparse_status_not_implemented – `trans` != rocsparse_operation_none or rocsparse_matrix_type != rocsparse_matrix_type_general.

## Sparse Level 3 Functions

This module holds all sparse level 3 routines.

The sparse level 3 routines describe operations between a matrix in sparse format and multiple vectors in dense format that can also be seen as a dense matrix.

### rocsparse_bsrmm()

rocsparse_status rocsparse_sbsrmm(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int mb, rocsparse_int n, rocsparse_int kb, rocsparse_int nnzb, const float *alpha, const rocsparse_mat_descr descr, const float *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, const float *B, rocsparse_int ldb, const float *beta, float *C, rocsparse_int ldc)

rocsparse_status rocsparse_dbsrmm(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int mb, rocsparse_int n, rocsparse_int kb, rocsparse_int nnzb, const double *alpha, const rocsparse_mat_descr descr, const double *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, const double *B, rocsparse_int ldb, const double *beta, double *C, rocsparse_int ldc)

rocsparse_status rocsparse_cbsrmm(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int mb, rocsparse_int n, rocsparse_int kb, rocsparse_int nnzb, const rocsparse_float_complex *alpha, const rocsparse_mat_descr descr, const rocsparse_float_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, const rocsparse_float_complex *B, rocsparse_int ldb, const rocsparse_float_complex *beta, rocsparse_float_complex *C, rocsparse_int ldc)

rocsparse_status rocsparse_zbsrmm(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int mb, rocsparse_int n, rocsparse_int kb, rocsparse_int nnzb, const rocsparse_double_complex *alpha, const rocsparse_mat_descr descr, const rocsparse_double_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, const rocsparse_double_complex *B, rocsparse_int ldb, const rocsparse_double_complex *beta, rocsparse_double_complex *C, rocsparse_int ldc)

  Sparse matrix dense matrix multiplication using BSR storage format.

  `rocsparse_bsrmm` multiplies the scalar \(\alpha\) with a sparse \(mb \times kb\) matrix \(A\), defined in BSR storage format, and the dense \(k \times n\) matrix \(B\) (where \(k = block\_dim \times kb\)) and adds the result to the dense \(m \times n\) matrix \(C\) (where \(m = block\_dim \times mb\)) that is multiplied by the scalar \(\beta\), such that

  \[ C := \alpha \cdot op(A) \cdot op(B) + \beta \cdot C, \]
  with
  \[\begin{split} op(A) = \left\{ \begin{array}{ll} A, & \text{if trans_A == rocsparse_operation_none} \\ \end{array} \right. \end{split}\]
  and
  \[\begin{split} op(B) = \left\{ \begin{array}{ll} B, & \text{if trans_B == rocsparse_operation_none} \\ B^T, & \text{if trans_B == rocsparse_operation_transpose} \\ \end{array} \right. \end{split}\]

  Example

    This example multiplies a BSR matrix with a dense matrix.

        //     1 2 0 3 0 0
        // A = 0 4 5 0 0 0
        //     0 0 0 7 8 0
        //     0 0 1 2 4 1

        rocsparse_int block_dim = 2;
        rocsparse_int mb   = 2;
        rocsparse_int kb   = 3;
        rocsparse_int nnzb = 4;
        rocsparse_direction dir = rocsparse_direction_row;

        bsr_row_ptr[mb+1]                 = {0, 2, 4};                                        // device memory
        bsr_col_ind[nnzb]                 = {0, 1, 1, 2};                                     // device memory
        bsr_val[nnzb*block_dim*block_dim] = {1, 2, 0, 4, 0, 3, 5, 0, 0, 7, 1, 2, 8, 0, 4, 1}; // device memory

        // Set dimension n of B
        rocsparse_int n = 64;
        rocsparse_int m = mb * block_dim;
        rocsparse_int k = kb * block_dim;

        // Allocate and generate dense matrix B
        std::vector<float> hB(k * n);
        for(rocsparse_int i = 0; i < k * n; ++i)
        {
            hB[i] = static_cast<float>(rand()) / RAND_MAX;
        }

        // Copy B to the device
        float* B;
        hipMalloc((void**)&B, sizeof(float) * k * n);
        hipMemcpy(B, hB.data(), sizeof(float) * k * n, hipMemcpyHostToDevice);

        // alpha and beta
        float alpha = 1.0f;
        float beta  = 0.0f;

        // Allocate memory for the resulting matrix C
        float* C;
        hipMalloc((void**)&C, sizeof(float) * m * n);

        // Perform the matrix multiplication
        rocsparse_sbsrmm(handle,
                         dir,
                         rocsparse_operation_none,
                         rocsparse_operation_none,
                         mb,
                         n,
                         kb,
                         nnzb,
                         &alpha,
                         descr,
                         bsr_val,
                         bsr_row_ptr,
                         bsr_col_ind,
                         block_dim,
                         B,
                         k,
                         &beta,
                         C,
                         m);

  Note

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

  Note

  Currently, only `trans_A` == rocsparse_operation_none is supported.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - dir – [in] the storage format of the blocks. Can be rocsparse_direction_row or rocsparse_direction_column.

    - trans_A – [in] matrix \(A\) operation type. Currently, only rocsparse_operation_none is supported.

    - trans_B – [in] matrix \(B\) operation type. Currently, only rocsparse_operation_none and rocsparse_operation_transpose are supported.

    - mb – [in] number of block rows of the sparse BSR matrix \(A\).

    - n – [in] number of columns of the dense matrix \(op(B)\) and \(C\).

    - kb – [in] number of block columns of the sparse BSR matrix \(A\).

    - nnzb – [in] number of non-zero blocks of the sparse BSR matrix \(A\).

    - alpha – [in] scalar \(\alpha\).

    - descr – [in] descriptor of the sparse BSR matrix \(A\). Currently, only rocsparse_matrix_type_general is supported.

    - bsr_val – [in] array of `nnzb*block_dim*block_dim` elements of the sparse BSR matrix \(A\).

    - bsr_row_ptr – [in] array of `mb+1` elements that point to the start of every block row of the sparse BSR matrix \(A\).

    - bsr_col_ind – [in] array of `nnzb` elements containing the block column indices of the sparse BSR matrix \(A\).

    - block_dim – [in] size of the blocks in the sparse BSR matrix.

    - B – [in] array of dimension \(ldb \times n\) ( \(op(B) == B\)), \(ldb \times k\) otherwise.

    - ldb – [in] leading dimension of \(B\), must be at least \(\max{(1, k)}\) ( \( op(B) == B\)) where \(k = block\_dim \times kb\), \(\max{(1, n)}\) otherwise.

    - beta – [in] scalar \(\beta\).

    - C – [inout] array of dimension \(ldc \times n\).

    - ldc – [in] leading dimension of \(C\), must be at least \(\max{(1, m)}\) ( \( op(A) == A\)) where \(m = block\_dim \times mb\), \(\max{(1, k)}\) where \(k = block\_dim \times kb\) otherwise.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `mb`, `n`, `kb`, `nnzb`, `ldb` or `ldc` is invalid.

    - rocsparse_status_invalid_pointer – `descr`, `alpha`, `bsr_val`, `bsr_row_ptr`, `bsr_col_ind`, `B`, `beta` or `C` pointer is invalid.

    - rocsparse_status_arch_mismatch – the device is not supported.

    - rocsparse_status_not_implemented – `trans_A` != rocsparse_operation_none or `trans_B` == rocsparse_operation_conjugate_transpose or rocsparse_matrix_type != rocsparse_matrix_type_general.

### rocsparse_gebsrmm()

rocsparse_status rocsparse_sgebsrmm(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int mb, rocsparse_int n, rocsparse_int kb, rocsparse_int nnzb, const float *alpha, const rocsparse_mat_descr descr, const float *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, const float *B, rocsparse_int ldb, const float *beta, float *C, rocsparse_int ldc)

rocsparse_status rocsparse_dgebsrmm(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int mb, rocsparse_int n, rocsparse_int kb, rocsparse_int nnzb, const double *alpha, const rocsparse_mat_descr descr, const double *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, const double *B, rocsparse_int ldb, const double *beta, double *C, rocsparse_int ldc)

rocsparse_status rocsparse_cgebsrmm(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int mb, rocsparse_int n, rocsparse_int kb, rocsparse_int nnzb, const rocsparse_float_complex *alpha, const rocsparse_mat_descr descr, const rocsparse_float_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, const rocsparse_float_complex *B, rocsparse_int ldb, const rocsparse_float_complex *beta, rocsparse_float_complex *C, rocsparse_int ldc)

rocsparse_status rocsparse_zgebsrmm(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int mb, rocsparse_int n, rocsparse_int kb, rocsparse_int nnzb, const rocsparse_double_complex *alpha, const rocsparse_mat_descr descr, const rocsparse_double_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, const rocsparse_double_complex *B, rocsparse_int ldb, const rocsparse_double_complex *beta, rocsparse_double_complex *C, rocsparse_int ldc)

  Sparse matrix dense matrix multiplication using GEneral BSR storage format.

  `rocsparse_gebsrmm` multiplies the scalar \(\alpha\) with a sparse \(mb \times kb\) matrix \(A\), defined in GEneral BSR storage format, and the dense \(k \times n\) matrix \(B\) (where \(k = col_block\_dim \times kb\)) and adds the result to the dense \(m \times n\) matrix \(C\) (where \(m = row_block\_dim \times mb\)) that is multiplied by the scalar \(\beta\), such that

  \[ C := \alpha \cdot op(A) \cdot op(B) + \beta \cdot C, \]
  with
  \[\begin{split} op(A) = \left\{ \begin{array}{ll} A, & \text{if trans_A == rocsparse_operation_none} \\ \end{array} \right. \end{split}\]
  and
  \[\begin{split} op(B) = \left\{ \begin{array}{ll} B, & \text{if trans_B == rocsparse_operation_none} \\ B^T, & \text{if trans_B == rocsparse_operation_transpose} \\ \end{array} \right. \end{split}\]

  Example

    This example multiplies a GEneral BSR matrix with a dense matrix.

        //     1 2 0 3 0 0
        // A = 0 4 5 0 0 0
        //     0 0 0 7 8 0
        //     0 0 1 2 4 1

        rocsparse_int row_block_dim = 2;
        rocsparse_int col_block_dim = 3;
        rocsparse_int mb   = 2;
        rocsparse_int kb   = 2;
        rocsparse_int nnzb = 4;
        rocsparse_direction dir = rocsparse_direction_row;

        bsr_row_ptr[mb+1]                 = {0, 2, 4};                                        // device memory
        bsr_col_ind[nnzb]                 = {0, 1, 0, 1};                                     // device memory
        bsr_val[nnzb*row_block_dim*col_block_dim] = {1, 2, 0, 0, 4, 5, 3, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 7, 8, 0, 2, 4, 1}; // device memory

        // Set dimension n of B
        rocsparse_int n = 64;
        rocsparse_int m = mb * row_block_dim;
        rocsparse_int k = kb * col_block_dim;

        // Allocate and generate dense matrix B
        std::vector<float> hB(k * n);
        for(rocsparse_int i = 0; i < k * n; ++i)
        {
            hB[i] = static_cast<float>(rand()) / RAND_MAX;
        }

        // Copy B to the device
        float* B;
        hipMalloc((void**)&B, sizeof(float) * k * n);
        hipMemcpy(B, hB.data(), sizeof(float) * k * n, hipMemcpyHostToDevice);

        // alpha and beta
        float alpha = 1.0f;
        float beta  = 0.0f;

        // Allocate memory for the resulting matrix C
        float* C;
        hipMalloc((void**)&C, sizeof(float) * m * n);

        // Perform the matrix multiplication
        rocsparse_sgebsrmm(handle,
                           dir,
                           rocsparse_operation_none,
                           rocsparse_operation_none,
                           mb,
                           n,
                           kb,
                           nnzb,
                           &alpha,
                           descr,
                           bsr_val,
                           bsr_row_ptr,
                           bsr_col_ind,
                           row_block_dim,
                           col_block_dim,
                           B,
                           k,
                           &beta,
                           C,
                           m);

  Note

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

  Note

  Currently, only `trans_A` == rocsparse_operation_none is supported.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - dir – [in] the storage format of the blocks. Can be rocsparse_direction_row or rocsparse_direction_column.

    - trans_A – [in] matrix \(A\) operation type. Currently, only rocsparse_operation_none is supported.

    - trans_B – [in] matrix \(B\) operation type. Currently, only rocsparse_operation_none and rocsparse_operation_transpose are supported.

    - mb – [in] number of block rows of the sparse GEneral BSR matrix \(A\).

    - n – [in] number of columns of the dense matrix \(op(B)\) and \(C\).

    - kb – [in] number of block columns of the sparse GEneral BSR matrix \(A\).

    - nnzb – [in] number of non-zero blocks of the sparse GEneral BSR matrix \(A\).

    - alpha – [in] scalar \(\alpha\).

    - descr – [in] descriptor of the sparse GEneral BSR matrix \(A\). Currently, only rocsparse_matrix_type_general is supported.

    - bsr_val – [in] array of `nnzb*row_block_dim*col_block_dim` elements of the sparse GEneral BSR matrix \(A\).

    - bsr_row_ptr – [in] array of `mb+1` elements that point to the start of every block row of the sparse GEneral BSR matrix \(A\).

    - bsr_col_ind – [in] array of `nnzb` elements containing the block column indices of the sparse GEneral BSR matrix \(A\).

    - row_block_dim – [in] row size of the blocks in the sparse GEneral BSR matrix.

    - col_block_dim – [in] column size of the blocks in the sparse GEneral BSR matrix.

    - B – [in] array of dimension \(ldb \times n\) ( \(op(B) == B\)), \(ldb \times k\) otherwise.

    - ldb – [in] leading dimension of \(B\), must be at least \(\max{(1, k)}\) ( \( op(B) == B\)) where \(k = col\_block\_dim \times kb\), \(\max{(1, n)}\) otherwise.

    - beta – [in] scalar \(\beta\).

    - C – [inout] array of dimension \(ldc \times n\).

    - ldc – [in] leading dimension of \(C\), must be at least \(\max{(1, m)}\) ( \( op(A) == A\)) where \(m = row\_block\_dim \times mb\), \(\max{(1, k)}\) where \(k = col\_block\_dim \times kb\) otherwise.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `mb`, `n`, `kb`, `nnzb`, `ldb`, `ldc`, `row_block_dim` or `col_block_dim` is invalid.

    - rocsparse_status_invalid_pointer – `descr`, `alpha`, `bsr_val`, `bsr_row_ptr`, `bsr_col_ind`, `B`, `beta` or `C` pointer is invalid.

    - rocsparse_status_arch_mismatch – the device is not supported.

    - rocsparse_status_not_implemented – `trans_A` != rocsparse_operation_none or `trans_B` == rocsparse_operation_conjugate_transpose or rocsparse_matrix_type != rocsparse_matrix_type_general.

### rocsparse_csrmm()

rocsparse_status rocsparse_scsrmm(rocsparse_handle handle, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int m, rocsparse_int n, rocsparse_int k, rocsparse_int nnz, const float *alpha, const rocsparse_mat_descr descr, const float *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, const float *B, rocsparse_int ldb, const float *beta, float *C, rocsparse_int ldc)

rocsparse_status rocsparse_dcsrmm(rocsparse_handle handle, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int m, rocsparse_int n, rocsparse_int k, rocsparse_int nnz, const double *alpha, const rocsparse_mat_descr descr, const double *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, const double *B, rocsparse_int ldb, const double *beta, double *C, rocsparse_int ldc)

rocsparse_status rocsparse_ccsrmm(rocsparse_handle handle, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int m, rocsparse_int n, rocsparse_int k, rocsparse_int nnz, const rocsparse_float_complex *alpha, const rocsparse_mat_descr descr, const rocsparse_float_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, const rocsparse_float_complex *B, rocsparse_int ldb, const rocsparse_float_complex *beta, rocsparse_float_complex *C, rocsparse_int ldc)

rocsparse_status rocsparse_zcsrmm(rocsparse_handle handle, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int m, rocsparse_int n, rocsparse_int k, rocsparse_int nnz, const rocsparse_double_complex *alpha, const rocsparse_mat_descr descr, const rocsparse_double_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, const rocsparse_double_complex *B, rocsparse_int ldb, const rocsparse_double_complex *beta, rocsparse_double_complex *C, rocsparse_int ldc)

  Sparse matrix dense matrix multiplication using CSR storage format.

  `rocsparse_csrmm` multiplies the scalar \(\alpha\) with a sparse \(m \times k\) matrix \(A\), defined in CSR storage format, and the dense \(k \times n\) matrix \(B\) and adds the result to the dense \(m \times n\) matrix \(C\) that is multiplied by the scalar \(\beta\), such that

  \[ C := \alpha \cdot op(A) \cdot op(B) + \beta \cdot C, \]
  with
  \[\begin{split} op(A) = \left\{ \begin{array}{ll} A, & \text{if trans_A == rocsparse_operation_none} \\ A^T, & \text{if trans_A == rocsparse_operation_transpose} \\ A^H, & \text{if trans_A == rocsparse_operation_conjugate_transpose} \end{array} \right. \end{split}\]
  and
  \[\begin{split} op(B) = \left\{ \begin{array}{ll} B, & \text{if trans_B == rocsparse_operation_none} \\ B^T, & \text{if trans_B == rocsparse_operation_transpose} \\ B^H, & \text{if trans_B == rocsparse_operation_conjugate_transpose} \end{array} \right. \end{split}\]

      for(i = 0; i < ldc; ++i)
      {
          for(j = 0; j < n; ++j)
          {
              C[i][j] = beta * C[i][j];

              for(k = csr_row_ptr[i]; k < csr_row_ptr[i + 1]; ++k)
              {
                  C[i][j] += alpha * csr_val[k] * B[csr_col_ind[k]][j];
              }
          }
      }

  Example

    This example multiplies a CSR matrix with a dense matrix.

        //     1 2 0 3 0
        // A = 0 4 5 0 0
        //     6 0 0 7 8

        rocsparse_int m   = 3;
        rocsparse_int k   = 5;
        rocsparse_int nnz = 8;

        csr_row_ptr[m+1] = {0, 3, 5, 8};             // device memory
        csr_col_ind[nnz] = {0, 1, 3, 1, 2, 0, 3, 4}; // device memory
        csr_val[nnz]     = {1, 2, 3, 4, 5, 6, 7, 8}; // device memory

        // Set dimension n of B
        rocsparse_int n = 64;

        // Allocate and generate dense matrix B
        std::vector<float> hB(k * n);
        for(rocsparse_int i = 0; i < k * n; ++i)
        {
            hB[i] = static_cast<float>(rand()) / RAND_MAX;
        }

        // Copy B to the device
        float* B;
        hipMalloc((void**)&B, sizeof(float) * k * n);
        hipMemcpy(B, hB.data(), sizeof(float) * k * n, hipMemcpyHostToDevice);

        // alpha and beta
        float alpha = 1.0f;
        float beta  = 0.0f;

        // Allocate memory for the resulting matrix C
        float* C;
        hipMalloc((void**)&C, sizeof(float) * m * n);

        // Perform the matrix multiplication
        rocsparse_scsrmm(handle,
                         rocsparse_operation_none,
                         rocsparse_operation_none,
                         m,
                         n,
                         k,
                         nnz,
                         &alpha,
                         descr,
                         csr_val,
                         csr_row_ptr,
                         csr_col_ind,
                         B,
                         k,
                         &beta,
                         C,
                         m);

  Note

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

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - trans_A – [in] matrix \(A\) operation type.

    - trans_B – [in] matrix \(B\) operation type.

    - m – [in] number of rows of the sparse CSR matrix \(A\).

    - n – [in] number of columns of the dense matrix \(op(B)\) and \(C\).

    - k – [in] number of columns of the sparse CSR matrix \(A\).

    - nnz – [in] number of non-zero entries of the sparse CSR matrix \(A\).

    - alpha – [in] scalar \(\alpha\).

    - descr – [in] descriptor of the sparse CSR matrix \(A\). Currently, only rocsparse_matrix_type_general is supported.

    - csr_val – [in] array of `nnz` elements of the sparse CSR matrix \(A\).

    - csr_row_ptr – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix \(A\).

    - csr_col_ind – [in] array of `nnz` elements containing the column indices of the sparse CSR matrix \(A\).

    - B – [in] array of dimension \(ldb \times n\) ( \(op(B) == B\)), \(ldb \times k\) otherwise.

    - ldb – [in] leading dimension of \(B\), must be at least \(\max{(1, k)}\) ( \(op(B) == B\)), \(\max{(1, n)}\) otherwise.

    - beta – [in] scalar \(\beta\).

    - C – [inout] array of dimension \(ldc \times n\).

    - ldc – [in] leading dimension of \(C\), must be at least \(\max{(1, m)}\) ( \(op(A) == A\)), \(\max{(1, k)}\) otherwise.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m`, `n`, `k`, `nnz`, `ldb` or `ldc` is invalid.

    - rocsparse_status_invalid_pointer – `descr`, `alpha`, `csr_val`, `csr_row_ptr`, `csr_col_ind`, `B`, `beta` or `C` pointer is invalid.

    - rocsparse_status_arch_mismatch – the device is not supported.

    - rocsparse_status_not_implemented – rocsparse_matrix_type != rocsparse_matrix_type_general.

### rocsparse_csrsm_zero_pivot()

rocsparse_status rocsparse_csrsm_zero_pivot(rocsparse_handle handle, rocsparse_mat_info info, rocsparse_int *position)

  Sparse triangular system solve using CSR storage format.

  `rocsparse_csrsm_zero_pivot` returns rocsparse_status_zero_pivot, if either a structural or numerical zero has been found during rocsparse_scsrsm_solve(), rocsparse_dcsrsm_solve(), rocsparse_ccsrsm_solve() or rocsparse_zcsrsm_solve() computation. The first zero pivot \(j\) at \(A_{j,j}\) is stored in `position`, using same index base as the CSR matrix.

  `position` can be in host or device memory. If no zero pivot has been found, `position` is set to -1 and rocsparse_status_success is returned instead.

  Note

  `rocsparse_csrsm_zero_pivot` is a blocking function. It might influence performance negatively.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - info – [in] structure that holds the information collected during the analysis step.

    - position – [inout] pointer to zero pivot \(j\), can be in host or device memory.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_pointer – `info` or `position` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

    - rocsparse_status_zero_pivot – zero pivot has been found.

### rocsparse_csrsm_buffer_size()

rocsparse_status rocsparse_scsrsm_buffer_size(rocsparse_handle handle, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int m, rocsparse_int nrhs, rocsparse_int nnz, const float *alpha, const rocsparse_mat_descr descr, const float *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, const float *B, rocsparse_int ldb, rocsparse_mat_info info, rocsparse_solve_policy policy, size_t *buffer_size)

rocsparse_status rocsparse_dcsrsm_buffer_size(rocsparse_handle handle, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int m, rocsparse_int nrhs, rocsparse_int nnz, const double *alpha, const rocsparse_mat_descr descr, const double *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, const double *B, rocsparse_int ldb, rocsparse_mat_info info, rocsparse_solve_policy policy, size_t *buffer_size)

rocsparse_status rocsparse_ccsrsm_buffer_size(rocsparse_handle handle, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int m, rocsparse_int nrhs, rocsparse_int nnz, const rocsparse_float_complex *alpha, const rocsparse_mat_descr descr, const rocsparse_float_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, const rocsparse_float_complex *B, rocsparse_int ldb, rocsparse_mat_info info, rocsparse_solve_policy policy, size_t *buffer_size)

rocsparse_status rocsparse_zcsrsm_buffer_size(rocsparse_handle handle, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int m, rocsparse_int nrhs, rocsparse_int nnz, const rocsparse_double_complex *alpha, const rocsparse_mat_descr descr, const rocsparse_double_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, const rocsparse_double_complex *B, rocsparse_int ldb, rocsparse_mat_info info, rocsparse_solve_policy policy, size_t *buffer_size)

  Sparse triangular system solve using CSR storage format.

  `rocsparse_csrsm_buffer_size` returns the size of the temporary storage buffer that is required by rocsparse_scsrsm_analysis(), rocsparse_dcsrsm_analysis(), rocsparse_ccsrsm_analysis(), rocsparse_zcsrsm_analysis(), rocsparse_scsrsm_solve(), rocsparse_dcsrsm_solve(), rocsparse_ccsrsm_solve() and rocsparse_zcsrsm_solve(). The temporary storage buffer must be allocated by the user.

  Note

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

  Note

  This routine supports execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - trans_A – [in] matrix A operation type.

    - trans_B – [in] matrix B operation type.

    - m – [in] number of rows of the sparse CSR matrix A.

    - nrhs – [in] number of columns of the dense matrix op(B).

    - nnz – [in] number of non-zero entries of the sparse CSR matrix A.

    - alpha – [in] scalar \(\alpha\).

    - descr – [in] descriptor of the sparse CSR matrix A.

    - csr_val – [in] array of `nnz` elements of the sparse CSR matrix A.

    - csr_row_ptr – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix A.

    - csr_col_ind – [in] array of `nnz` elements containing the column indices of the sparse CSR matrix A.

    - B – [in] array of `m` \(\times\) `nrhs` elements of the rhs matrix B.

    - ldb – [in] leading dimension of rhs matrix B.

    - info – [in] structure that holds the information collected during the analysis step.

    - policy – [in] rocsparse_solve_policy_auto.

    - buffer_size – [out] number of bytes of the temporary storage buffer required by rocsparse_scsrsm_analysis(), rocsparse_dcsrsm_analysis(), rocsparse_ccsrsm_analysis(), rocsparse_zcsrsm_analysis(), rocsparse_scsrsm_solve(), rocsparse_dcsrsm_solve(), rocsparse_ccsrsm_solve() and rocsparse_zcsrsm_solve().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m`, `nrhs` or `nnz` is invalid.

    - rocsparse_status_invalid_pointer – `alpha`, `descr`, `csr_val`, `csr_row_ptr`, `csr_col_ind`, `B`, `info` or `buffer_size` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

    - rocsparse_status_not_implemented – `trans_A` == rocsparse_operation_conjugate_transpose, `trans_B` == rocsparse_operation_conjugate_transpose or rocsparse_matrix_type != rocsparse_matrix_type_general.

### rocsparse_csrsm_analysis()

rocsparse_status rocsparse_scsrsm_analysis(rocsparse_handle handle, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int m, rocsparse_int nrhs, rocsparse_int nnz, const float *alpha, const rocsparse_mat_descr descr, const float *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, const float *B, rocsparse_int ldb, rocsparse_mat_info info, rocsparse_analysis_policy analysis, rocsparse_solve_policy solve, void *temp_buffer)

rocsparse_status rocsparse_dcsrsm_analysis(rocsparse_handle handle, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int m, rocsparse_int nrhs, rocsparse_int nnz, const double *alpha, const rocsparse_mat_descr descr, const double *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, const double *B, rocsparse_int ldb, rocsparse_mat_info info, rocsparse_analysis_policy analysis, rocsparse_solve_policy solve, void *temp_buffer)

rocsparse_status rocsparse_ccsrsm_analysis(rocsparse_handle handle, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int m, rocsparse_int nrhs, rocsparse_int nnz, const rocsparse_float_complex *alpha, const rocsparse_mat_descr descr, const rocsparse_float_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, const rocsparse_float_complex *B, rocsparse_int ldb, rocsparse_mat_info info, rocsparse_analysis_policy analysis, rocsparse_solve_policy solve, void *temp_buffer)

rocsparse_status rocsparse_zcsrsm_analysis(rocsparse_handle handle, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int m, rocsparse_int nrhs, rocsparse_int nnz, const rocsparse_double_complex *alpha, const rocsparse_mat_descr descr, const rocsparse_double_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, const rocsparse_double_complex *B, rocsparse_int ldb, rocsparse_mat_info info, rocsparse_analysis_policy analysis, rocsparse_solve_policy solve, void *temp_buffer)

  Sparse triangular system solve using CSR storage format.

  `rocsparse_csrsm_analysis` performs the analysis step for rocsparse_scsrsm_solve(), rocsparse_dcsrsm_solve(), rocsparse_ccsrsm_solve() and rocsparse_zcsrsm_solve(). It is expected that this function will be executed only once for a given matrix and particular operation type. The analysis meta data can be cleared by rocsparse_csrsm_clear().

  `rocsparse_csrsm_analysis` can share its meta data with rocsparse_scsrilu0_analysis(), rocsparse_dcsrilu0_analysis(), rocsparse_ccsrilu0_analysis(), rocsparse_zcsrilu0_analysis(), rocsparse_scsric0_analysis(), rocsparse_dcsric0_analysis(), rocsparse_ccsric0_analysis(), rocsparse_zcsric0_analysis(), rocsparse_scsrsv_analysis(), rocsparse_dcsrsv_analysis(), rocsparse_ccsrsv_analysis() and rocsparse_zcsrsv_analysis(). Selecting rocsparse_analysis_policy_reuse policy can greatly improve computation performance of meta data. However, the user need to make sure that the sparsity pattern remains unchanged. If this cannot be assured, rocsparse_analysis_policy_force has to be used.

  Note

  If the matrix sparsity pattern changes, the gathered information will become invalid.

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - trans_A – [in] matrix A operation type.

    - trans_B – [in] matrix B operation type.

    - m – [in] number of rows of the sparse CSR matrix A.

    - nrhs – [in] number of columns of the dense matrix op(B).

    - nnz – [in] number of non-zero entries of the sparse CSR matrix A.

    - alpha – [in] scalar \(\alpha\).

    - descr – [in] descriptor of the sparse CSR matrix A.

    - csr_val – [in] array of `nnz` elements of the sparse CSR matrix A.

    - csr_row_ptr – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix A.

    - csr_col_ind – [in] array of `nnz` elements containing the column indices of the sparse CSR matrix A.

    - B – [in] array of `m` \(\times\) `nrhs` elements of the rhs matrix B.

    - ldb – [in] leading dimension of rhs matrix B.

    - info – [out] structure that holds the information collected during the analysis step.

    - analysis – [in] rocsparse_analysis_policy_reuse or rocsparse_analysis_policy_force.

    - solve – [in] rocsparse_solve_policy_auto.

    - temp_buffer – [in] temporary storage buffer allocated by the user.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m`, `nrhs` or `nnz` is invalid.

    - rocsparse_status_invalid_pointer – `alpha`, `descr`, `csr_val`, `csr_row_ptr`, `csr_col_ind`, `B`, `info` or `temp_buffer` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

    - rocsparse_status_not_implemented – `trans_A` == rocsparse_operation_conjugate_transpose, `trans_B` == rocsparse_operation_conjugate_transpose or rocsparse_matrix_type != rocsparse_matrix_type_general.

### rocsparse_csrsm_solve()

rocsparse_status rocsparse_scsrsm_solve(rocsparse_handle handle, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int m, rocsparse_int nrhs, rocsparse_int nnz, const float *alpha, const rocsparse_mat_descr descr, const float *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, float *B, rocsparse_int ldb, rocsparse_mat_info info, rocsparse_solve_policy policy, void *temp_buffer)

rocsparse_status rocsparse_dcsrsm_solve(rocsparse_handle handle, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int m, rocsparse_int nrhs, rocsparse_int nnz, const double *alpha, const rocsparse_mat_descr descr, const double *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, double *B, rocsparse_int ldb, rocsparse_mat_info info, rocsparse_solve_policy policy, void *temp_buffer)

rocsparse_status rocsparse_ccsrsm_solve(rocsparse_handle handle, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int m, rocsparse_int nrhs, rocsparse_int nnz, const rocsparse_float_complex *alpha, const rocsparse_mat_descr descr, const rocsparse_float_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_float_complex *B, rocsparse_int ldb, rocsparse_mat_info info, rocsparse_solve_policy policy, void *temp_buffer)

rocsparse_status rocsparse_zcsrsm_solve(rocsparse_handle handle, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int m, rocsparse_int nrhs, rocsparse_int nnz, const rocsparse_double_complex *alpha, const rocsparse_mat_descr descr, const rocsparse_double_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_double_complex *B, rocsparse_int ldb, rocsparse_mat_info info, rocsparse_solve_policy policy, void *temp_buffer)

  Sparse triangular system solve using CSR storage format.

  `rocsparse_csrsm_solve` solves a sparse triangular linear system of a sparse \(m \times m\) matrix, defined in CSR storage format, a dense solution matrix \(X\) and the right-hand side matrix \(B\) that is multiplied by \(\alpha\), such that

  \[ op(A) \cdot op(X) = \alpha \cdot op(B), \]
  with
  \[\begin{split} op(A) = \left\{ \begin{array}{ll} A, & \text{if trans_A == rocsparse_operation_none} \\ A^T, & \text{if trans_A == rocsparse_operation_transpose} \\ A^H, & \text{if trans_A == rocsparse_operation_conjugate_transpose} \end{array} \right. \end{split}\]
  ,
  \[\begin{split} op(B) = \left\{ \begin{array}{ll} B, & \text{if trans_B == rocsparse_operation_none} \\ B^T, & \text{if trans_B == rocsparse_operation_transpose} \\ B^H, & \text{if trans_B == rocsparse_operation_conjugate_transpose} \end{array} \right. \end{split}\]
  and
  \[\begin{split} op(X) = \left\{ \begin{array}{ll} X, & \text{if trans_B == rocsparse_operation_none} \\ X^T, & \text{if trans_B == rocsparse_operation_transpose} \\ X^H, & \text{if trans_B == rocsparse_operation_conjugate_transpose} \end{array} \right. \end{split}\]

  `rocsparse_csrsm_solve` requires a user allocated temporary buffer. Its size is returned by rocsparse_scsrsm_buffer_size(), rocsparse_dcsrsm_buffer_size(), rocsparse_ccsrsm_buffer_size() or rocsparse_zcsrsm_buffer_size(). Furthermore, analysis meta data is required. It can be obtained by rocsparse_scsrsm_analysis(), rocsparse_dcsrsm_analysis(), rocsparse_ccsrsm_analysis() or rocsparse_zcsrsm_analysis(). `rocsparse_csrsm_solve` reports the first zero pivot (either numerical or structural zero). The zero pivot status can be checked calling rocsparse_csrsm_zero_pivot(). If rocsparse_diag_type == rocsparse_diag_type_unit, no zero pivot will be reported, even if \(A_{j,j} = 0\) for some \(j\).

  Example

    Consider the lower triangular \(m \times m\) matrix \(L\), stored in CSR storage format with unit diagonal. The following example solves \(L \cdot X = B\).

        // Create rocSPARSE handle
        rocsparse_handle handle;
        rocsparse_create_handle(&handle);

        // Create matrix descriptor
        rocsparse_mat_descr descr;
        rocsparse_create_mat_descr(&descr);
        rocsparse_set_mat_fill_mode(descr, rocsparse_fill_mode_lower);
        rocsparse_set_mat_diag_type(descr, rocsparse_diag_type_unit);

        // Create matrix info structure
        rocsparse_mat_info info;
        rocsparse_create_mat_info(&info);

        // Obtain required buffer size
        size_t buffer_size;
        rocsparse_dcsrsm_buffer_size(handle,
                                     rocsparse_operation_none,
                                     rocsparse_operation_none,
                                     m,
                                     nrhs,
                                     nnz,
                                     &alpha,
                                     descr,
                                     csr_val,
                                     csr_row_ptr,
                                     csr_col_ind,
                                     B,
                                     ldb,
                                     info,
                                     rocsparse_solve_policy_auto,
                                     &buffer_size);

        // Allocate temporary buffer
        void* temp_buffer;
        hipMalloc(&temp_buffer, buffer_size);

        // Perform analysis step
        rocsparse_dcsrsm_analysis(handle,
                                  rocsparse_operation_none,
                                  rocsparse_operation_none,
                                  m,
                                  nrhs,
                                  nnz,
                                  &alpha,
                                  descr,
                                  csr_val,
                                  csr_row_ptr,
                                  csr_col_ind,
                                  B,
                                  ldb,
                                  info,
                                  rocsparse_analysis_policy_reuse,
                                  rocsparse_solve_policy_auto,
                                  temp_buffer);

        // Solve LX = B
        rocsparse_dcsrsm_solve(handle,
                               rocsparse_operation_none,
                               rocsparse_operation_none,
                               m,
                               nrhs,
                               nnz,
                               &alpha,
                               descr,
                               csr_val,
                               csr_row_ptr,
                               csr_col_ind,
                               B,
                               ldb,
                               info,
                               rocsparse_solve_policy_auto,
                               temp_buffer);

        // No zero pivot should be found, with L having unit diagonal

        // Clean up
        hipFree(temp_buffer);
        rocsparse_destroy_mat_info(info);
        rocsparse_destroy_mat_descr(descr);
        rocsparse_destroy_handle(handle);

  Note

  The sparse CSR matrix has to be sorted. This can be achieved by calling rocsparse_csrsort().

  Note

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

  Note

  Currently, only `trans_A` != rocsparse_operation_conjugate_transpose and `trans_B` != rocsparse_operation_conjugate_transpose is supported.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - trans_A – [in] matrix A operation type.

    - trans_B – [in] matrix B operation type.

    - m – [in] number of rows of the sparse CSR matrix A.

    - nrhs – [in] number of columns of the dense matrix op(B).

    - nnz – [in] number of non-zero entries of the sparse CSR matrix A.

    - alpha – [in] scalar \(\alpha\).

    - descr – [in] descriptor of the sparse CSR matrix A.

    - csr_val – [in] array of `nnz` elements of the sparse CSR matrix A.

    - csr_row_ptr – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix A.

    - csr_col_ind – [in] array of `nnz` elements containing the column indices of the sparse CSR matrix A.

    - B – [inout] array of `m` \(\times\) `nrhs` elements of the rhs matrix B.

    - ldb – [in] leading dimension of rhs matrix B.

    - info – [in] structure that holds the information collected during the analysis step.

    - policy – [in] rocsparse_solve_policy_auto.

    - temp_buffer – [in] temporary storage buffer allocated by the user.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m`, `nrhs` or `nnz` is invalid.

    - rocsparse_status_invalid_pointer – `alpha`, `descr`, `csr_val`, `csr_row_ptr`, `csr_col_ind`, `B`, `info` or `temp_buffer` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

    - rocsparse_status_not_implemented – `trans_A` == rocsparse_operation_conjugate_transpose, `trans_B` == rocsparse_operation_conjugate_transpose or rocsparse_matrix_type != rocsparse_matrix_type_general.

### rocsparse_csrsm_clear()

rocsparse_status rocsparse_csrsm_clear(rocsparse_handle handle, rocsparse_mat_info info)

  Sparse triangular system solve using CSR storage format.

  `rocsparse_csrsm_clear` deallocates all memory that was allocated by rocsparse_scsrsm_analysis(), rocsparse_dcsrsm_analysis(), rocsparse_ccsrsm_analysis() or rocsparse_zcsrsm_analysis(). This is especially useful, if memory is an issue and the analysis data is not required for further computation, e.g. when switching to another sparse matrix format. Calling `rocsparse_csrsm_clear` is optional. All allocated resources will be cleared, when the opaque rocsparse_mat_info struct is destroyed using rocsparse_destroy_mat_info().

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - info – [inout] structure that holds the information collected during the analysis step.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_pointer – `info` pointer is invalid.

    - rocsparse_status_memory_error – the buffer holding the meta data could not be deallocated.

    - rocsparse_status_internal_error – an internal error occurred.

### rocsparse_bsrsm_zero_pivot()

rocsparse_status rocsparse_bsrsm_zero_pivot(rocsparse_handle handle, rocsparse_mat_info info, rocsparse_int *position)

  Sparse triangular system solve using BSR storage format.

  `rocsparse_bsrsm_zero_pivot` returns rocsparse_status_zero_pivot, if either a structural or numerical zero has been found during rocsparse_sbsrsm_solve(), rocsparse_dbsrsm_solve(), rocsparse_cbsrsm_solve() or rocsparse_zbsrsm_solve() computation. The first zero pivot \(j\) at \(A_{j,j}\) is stored in `position`, using same index base as the BSR matrix.

  `position` can be in host or device memory. If no zero pivot has been found, `position` is set to -1 and rocsparse_status_success is returned instead.

  Note

  `rocsparse_bsrsm_zero_pivot` is a blocking function. It might influence performance negatively.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - info – [in] structure that holds the information collected during the analysis step.

    - position – [inout] pointer to zero pivot \(j\), can be in host or device memory.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_pointer – `info` or `position` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

    - rocsparse_status_zero_pivot – zero pivot has been found.

### rocsparse_bsrsm_buffer_size()

rocsparse_status rocsparse_sbsrsm_buffer_size(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans_A, rocsparse_operation trans_X, rocsparse_int mb, rocsparse_int nrhs, rocsparse_int nnzb, const rocsparse_mat_descr descr, const float *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, size_t *buffer_size)

rocsparse_status rocsparse_dbsrsm_buffer_size(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans_A, rocsparse_operation trans_X, rocsparse_int mb, rocsparse_int nrhs, rocsparse_int nnzb, const rocsparse_mat_descr descr, const double *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, size_t *buffer_size)

rocsparse_status rocsparse_cbsrsm_buffer_size(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans_A, rocsparse_operation trans_X, rocsparse_int mb, rocsparse_int nrhs, rocsparse_int nnzb, const rocsparse_mat_descr descr, const rocsparse_float_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, size_t *buffer_size)

rocsparse_status rocsparse_zbsrsm_buffer_size(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans_A, rocsparse_operation trans_X, rocsparse_int mb, rocsparse_int nrhs, rocsparse_int nnzb, const rocsparse_mat_descr descr, const rocsparse_double_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, size_t *buffer_size)

  Sparse triangular system solve using BSR storage format.

  `rocsparse_bsrsm_buffer_size` returns the size of the temporary storage buffer that is required by rocsparse_sbsrsm_analysis(), rocsparse_dbsrsm_analysis(), rocsparse_cbsrsm_analysis(), rocsparse_zbsrsm_analysis(), rocsparse_sbsrsm_solve(), rocsparse_dbsrsm_solve(), rocsparse_cbsrsm_solve() and rocsparse_zbsrsm_solve(). The temporary storage buffer must be allocated by the user.

  Note

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

  Note

  This routine supports execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - dir – [in] matrix storage of BSR blocks.

    - trans_A – [in] matrix A operation type.

    - trans_X – [in] matrix X operation type.

    - mb – [in] number of block rows of the sparse BSR matrix A.

    - nrhs – [in] number of columns of the dense matrix op(X).

    - nnzb – [in] number of non-zero blocks of the sparse BSR matrix A.

    - descr – [in] descriptor of the sparse BSR matrix A.

    - bsr_val – [in] array of `nnzb` blocks of the sparse BSR matrix.

    - bsr_row_ptr – [in] array of `mb+1` elements that point to the start of every block row of the sparse BSR matrix.

    - bsr_col_ind – [in] array of `nnzb` containing the block column indices of the sparse BSR matrix.

    - block_dim – [in] block dimension of the sparse BSR matrix.

    - info – [in] structure that holds the information collected during the analysis step.

    - buffer_size – [out] number of bytes of the temporary storage buffer required by rocsparse_sbsrsm_analysis(), rocsparse_dbsrsm_analysis(), rocsparse_cbsrsm_analysis(), rocsparse_zbsrsm_analysis(), rocsparse_sbsrsm_solve(), rocsparse_dbsrsm_solve(), rocsparse_cbsrsm_solve() and rocsparse_zbsrsm_solve().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `mb`, `nrhs`, `nnzb` or `block_dim` is invalid.

    - rocsparse_status_invalid_pointer – `descr`, `bsr_val`, `bsr_row_ptr`, `bsr_col_ind`, `info` or `buffer_size` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

    - rocsparse_status_not_implemented – `trans_A` == rocsparse_operation_conjugate_transpose, `trans_X` == rocsparse_operation_conjugate_transpose or rocsparse_matrix_type != rocsparse_matrix_type_general.

### rocsparse_bsrsm_analysis()

rocsparse_status rocsparse_sbsrsm_analysis(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans_A, rocsparse_operation trans_X, rocsparse_int mb, rocsparse_int nrhs, rocsparse_int nnzb, const rocsparse_mat_descr descr, const float *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, rocsparse_analysis_policy analysis, rocsparse_solve_policy solve, void *temp_buffer)

rocsparse_status rocsparse_dbsrsm_analysis(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans_A, rocsparse_operation trans_X, rocsparse_int mb, rocsparse_int nrhs, rocsparse_int nnzb, const rocsparse_mat_descr descr, const double *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, rocsparse_analysis_policy analysis, rocsparse_solve_policy solve, void *temp_buffer)

rocsparse_status rocsparse_cbsrsm_analysis(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans_A, rocsparse_operation trans_X, rocsparse_int mb, rocsparse_int nrhs, rocsparse_int nnzb, const rocsparse_mat_descr descr, const rocsparse_float_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, rocsparse_analysis_policy analysis, rocsparse_solve_policy solve, void *temp_buffer)

rocsparse_status rocsparse_zbsrsm_analysis(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans_A, rocsparse_operation trans_X, rocsparse_int mb, rocsparse_int nrhs, rocsparse_int nnzb, const rocsparse_mat_descr descr, const rocsparse_double_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, rocsparse_analysis_policy analysis, rocsparse_solve_policy solve, void *temp_buffer)

  Sparse triangular system solve using BSR storage format.

  `rocsparse_bsrsm_analysis` performs the analysis step for rocsparse_sbsrsm_solve(), rocsparse_dbsrsm_solve(), rocsparse_cbsrsm_solve() and rocsparse_zbsrsm_solve(). It is expected that this function will be executed only once for a given matrix and particular operation type. The analysis meta data can be cleared by rocsparse_bsrsm_clear().

  `rocsparse_bsrsm_analysis` can share its meta data with rocsparse_sbsrilu0_analysis(), rocsparse_dbsrilu0_analysis(), rocsparse_cbsrilu0_analysis(), rocsparse_zbsrilu0_analysis(), rocsparse_sbsric0_analysis(), rocsparse_dbsric0_analysis(), rocsparse_cbsric0_analysis(), rocsparse_zbsric0_analysis(), rocsparse_sbsrsv_analysis(), rocsparse_dbsrsv_analysis(), rocsparse_cbsrsv_analysis() and rocsparse_zbsrsv_analysis(). Selecting rocsparse_analysis_policy_reuse policy can greatly improve computation performance of meta data. However, the user need to make sure that the sparsity pattern remains unchanged. If this cannot be assured, rocsparse_analysis_policy_force has to be used.

  Note

  If the matrix sparsity pattern changes, the gathered information will become invalid.

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - dir – [in] matrix storage of BSR blocks.

    - trans_A – [in] matrix A operation type.

    - trans_X – [in] matrix X operation type.

    - mb – [in] number of block rows of the sparse BSR matrix A.

    - nrhs – [in] number of columns of the dense matrix op(X).

    - nnzb – [in] number of non-zero blocks of the sparse BSR matrix A.

    - descr – [in] descriptor of the sparse BSR matrix A.

    - bsr_val – [in] array of `nnzb` blocks of the sparse BSR matrix A.

    - bsr_row_ptr – [in] array of `mb+1` elements that point to the start of every block row of the sparse BSR matrix A.

    - bsr_col_ind – [in] array of `nnzb` containing the block column indices of the sparse BSR matrix A.

    - block_dim – [in] block dimension of the sparse BSR matrix A.

    - info – [out] structure that holds the information collected during the analysis step.

    - analysis – [in] rocsparse_analysis_policy_reuse or rocsparse_analysis_policy_force.

    - solve – [in] rocsparse_solve_policy_auto.

    - temp_buffer – [in] temporary storage buffer allocated by the user.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `mb`, `nrhs`, `nnzb` or `block_dim` is invalid.

    - rocsparse_status_invalid_pointer – `descr`, `bsr_val`, `bsr_row_ptr`, `bsr_col_ind`, `info` or `temp_buffer` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

    - rocsparse_status_not_implemented – `trans_A` == rocsparse_operation_conjugate_transpose, `trans_X` == rocsparse_operation_conjugate_transpose or rocsparse_matrix_type != rocsparse_matrix_type_general.

### rocsparse_bsrsm_solve()

rocsparse_status rocsparse_sbsrsm_solve(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans_A, rocsparse_operation trans_X, rocsparse_int mb, rocsparse_int nrhs, rocsparse_int nnzb, const float *alpha, const rocsparse_mat_descr descr, const float *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, const float *B, rocsparse_int ldb, float *X, rocsparse_int ldx, rocsparse_solve_policy policy, void *temp_buffer)

rocsparse_status rocsparse_dbsrsm_solve(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans_A, rocsparse_operation trans_X, rocsparse_int mb, rocsparse_int nrhs, rocsparse_int nnzb, const double *alpha, const rocsparse_mat_descr descr, const double *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, const double *B, rocsparse_int ldb, double *X, rocsparse_int ldx, rocsparse_solve_policy policy, void *temp_buffer)

rocsparse_status rocsparse_cbsrsm_solve(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans_A, rocsparse_operation trans_X, rocsparse_int mb, rocsparse_int nrhs, rocsparse_int nnzb, const rocsparse_float_complex *alpha, const rocsparse_mat_descr descr, const rocsparse_float_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, const rocsparse_float_complex *B, rocsparse_int ldb, rocsparse_float_complex *X, rocsparse_int ldx, rocsparse_solve_policy policy, void *temp_buffer)

rocsparse_status rocsparse_zbsrsm_solve(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans_A, rocsparse_operation trans_X, rocsparse_int mb, rocsparse_int nrhs, rocsparse_int nnzb, const rocsparse_double_complex *alpha, const rocsparse_mat_descr descr, const rocsparse_double_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, const rocsparse_double_complex *B, rocsparse_int ldb, rocsparse_double_complex *X, rocsparse_int ldx, rocsparse_solve_policy policy, void *temp_buffer)

  Sparse triangular system solve using BSR storage format.

  `rocsparse_bsrsm_solve` solves a sparse triangular linear system of a sparse \(m \times m\) matrix, defined in BSR storage format, a dense solution matrix \(X\) and the right-hand side matrix \(B\) that is multiplied by \(\alpha\), such that

  \[ op(A) \cdot op(X) = \alpha \cdot op(B), \]
  with
  \[\begin{split} op(A) = \left\{ \begin{array}{ll} A, & \text{if trans_A == rocsparse_operation_none} \\ A^T, & \text{if trans_A == rocsparse_operation_transpose} \\ A^H, & \text{if trans_A == rocsparse_operation_conjugate_transpose} \end{array} \right. \end{split}\]
  ,
  \[\begin{split} op(X) = \left\{ \begin{array}{ll} X, & \text{if trans_X == rocsparse_operation_none} \\ X^T, & \text{if trans_X == rocsparse_operation_transpose} \\ X^H, & \text{if trans_X == rocsparse_operation_conjugate_transpose} \end{array} \right. \end{split}\]

  `rocsparse_bsrsm_solve` requires a user allocated temporary buffer. Its size is returned by rocsparse_sbsrsm_buffer_size(), rocsparse_dbsrsm_buffer_size(), rocsparse_cbsrsm_buffer_size() or rocsparse_zbsrsm_buffer_size(). Furthermore, analysis meta data is required. It can be obtained by rocsparse_sbsrsm_analysis(), rocsparse_dbsrsm_analysis(), rocsparse_cbsrsm_analysis() or rocsparse_zbsrsm_analysis(). `rocsparse_bsrsm_solve` reports the first zero pivot (either numerical or structural zero). The zero pivot status can be checked calling rocsparse_bsrsm_zero_pivot(). If rocsparse_diag_type == rocsparse_diag_type_unit, no zero pivot will be reported, even if \(A_{j,j} = 0\) for some \(j\).

  Note

  The sparse BSR matrix has to be sorted.

  Note

  Operation type of B and X must match, if \(op(B)=B, op(X)=X\).

  Note

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

  Note

  Currently, only `trans_A` != rocsparse_operation_conjugate_transpose and `trans_X` != rocsparse_operation_conjugate_transpose is supported.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - dir – [in] matrix storage of BSR blocks.

    - trans_A – [in] matrix A operation type.

    - trans_X – [in] matrix X operation type.

    - mb – [in] number of block rows of the sparse BSR matrix A.

    - nrhs – [in] number of columns of the dense matrix op(X).

    - nnzb – [in] number of non-zero blocks of the sparse BSR matrix A.

    - alpha – [in] scalar \(\alpha\).

    - descr – [in] descriptor of the sparse BSR matrix A.

    - bsr_val – [in] array of `nnzb` blocks of the sparse BSR matrix.

    - bsr_row_ptr – [in] array of `mb+1` elements that point to the start of every block row of the sparse BSR matrix.

    - bsr_col_ind – [in] array of `nnzb` containing the block column indices of the sparse BSR matrix.

    - block_dim – [in] block dimension of the sparse BSR matrix.

    - info – [in] structure that holds the information collected during the analysis step.

    - B – [in] rhs matrix B with leading dimension `ldb`.

    - ldb – [in] leading dimension of rhs matrix B.

    - X – [out] solution matrix X with leading dimension `ldx`.

    - ldx – [in] leading dimension of solution matrix X.

    - policy – [in] rocsparse_solve_policy_auto.

    - temp_buffer – [in] temporary storage buffer allocated by the user.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `mb`, `nrhs`, `nnzb` or `block_dim` is invalid.

    - rocsparse_status_invalid_pointer – `alpha`, `descr`, `bsr_val`, `bsr_row_ptr`, `bsr_col_ind`, `B`, `X` `info` or `temp_buffer` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

    - rocsparse_status_not_implemented – `trans_A` == rocsparse_operation_conjugate_transpose, `trans_X` == rocsparse_operation_conjugate_transpose or rocsparse_matrix_type != rocsparse_matrix_type_general.

### rocsparse_bsrsm_clear()

rocsparse_status rocsparse_bsrsm_clear(rocsparse_handle handle, rocsparse_mat_info info)

  Sparse triangular system solve using BSR storage format.

  `rocsparse_bsrsm_clear` deallocates all memory that was allocated by rocsparse_sbsrsm_analysis(), rocsparse_dbsrsm_analysis(), rocsparse_cbsrsm_analysis() or rocsparse_zbsrsm_analysis(). This is especially useful, if memory is an issue and the analysis data is not required for further computation, e.g. when switching to another sparse matrix format. Calling `rocsparse_bsrsm_clear` is optional. All allocated resources will be cleared, when the opaque rocsparse_mat_info struct is destroyed using rocsparse_destroy_mat_info().

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - info – [inout] structure that holds the information collected during the analysis step.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_pointer – `info` pointer is invalid.

    - rocsparse_status_memory_error – the buffer holding the meta data could not be deallocated.

    - rocsparse_status_internal_error – an internal error occurred.

### rocsparse_gemmi()

rocsparse_status rocsparse_sgemmi(rocsparse_handle handle, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int m, rocsparse_int n, rocsparse_int k, rocsparse_int nnz, const float *alpha, const float *A, rocsparse_int lda, const rocsparse_mat_descr descr, const float *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, const float *beta, float *C, rocsparse_int ldc)

rocsparse_status rocsparse_dgemmi(rocsparse_handle handle, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int m, rocsparse_int n, rocsparse_int k, rocsparse_int nnz, const double *alpha, const double *A, rocsparse_int lda, const rocsparse_mat_descr descr, const double *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, const double *beta, double *C, rocsparse_int ldc)

rocsparse_status rocsparse_cgemmi(rocsparse_handle handle, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int m, rocsparse_int n, rocsparse_int k, rocsparse_int nnz, const rocsparse_float_complex *alpha, const rocsparse_float_complex *A, rocsparse_int lda, const rocsparse_mat_descr descr, const rocsparse_float_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, const rocsparse_float_complex *beta, rocsparse_float_complex *C, rocsparse_int ldc)

rocsparse_status rocsparse_zgemmi(rocsparse_handle handle, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int m, rocsparse_int n, rocsparse_int k, rocsparse_int nnz, const rocsparse_double_complex *alpha, const rocsparse_double_complex *A, rocsparse_int lda, const rocsparse_mat_descr descr, const rocsparse_double_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, const rocsparse_double_complex *beta, rocsparse_double_complex *C, rocsparse_int ldc)

  Dense matrix sparse matrix multiplication using CSR storage format.

  `rocsparse_gemmi` multiplies the scalar \(\alpha\) with a dense \(m \times k\) matrix \(A\) and the sparse \(k \times n\) matrix \(B\), defined in CSR storage format and adds the result to the dense \(m \times n\) matrix \(C\) that is multiplied by the scalar \(\beta\), such that

  \[ C := \alpha \cdot op(A) \cdot op(B) + \beta \cdot C \]
  with
  \[\begin{split} op(A) = \left\{ \begin{array}{ll} A, & \text{if trans_A == rocsparse_operation_none} \\ A^T, & \text{if trans_A == rocsparse_operation_transpose} \\ A^H, & \text{if trans_A == rocsparse_operation_conjugate_transpose} \end{array} \right. \end{split}\]
  and
  \[\begin{split} op(B) = \left\{ \begin{array}{ll} B, & \text{if trans_B == rocsparse_operation_none} \\ B^T, & \text{if trans_B == rocsparse_operation_transpose} \\ B^H, & \text{if trans_B == rocsparse_operation_conjugate_transpose} \end{array} \right. \end{split}\]

  Example

    This example multiplies a dense matrix with a CSC matrix.

        rocsparse_int m   = 2;
        rocsparse_int n   = 5;
        rocsparse_int k   = 3;
        rocsparse_int nnz = 8;
        rocsparse_int lda = m;
        rocsparse_int ldc = m;

        // Matrix A (m x k)
        // (  9.0  10.0  11.0 )
        // ( 12.0  13.0  14.0 )

        // Matrix B (k x n)
        // ( 1.0  2.0  0.0  3.0  0.0 )
        // ( 0.0  4.0  5.0  0.0  0.0 )
        // ( 6.0  0.0  0.0  7.0  8.0 )

        // Matrix C (m x n)
        // ( 15.0  16.0  17.0  18.0  19.0 )
        // ( 20.0  21.0  22.0  23.0  24.0 )

        A[lda * k]           = {9.0, 12.0, 10.0, 13.0, 11.0, 14.0};      // device memory
        csc_col_ptr_B[n + 1] = {0, 2, 4, 5, 7, 8};                       // device memory
        csc_row_ind_B[nnz]   = {0, 0, 1, 1, 2, 3, 3, 4};                 // device memory
        csc_val_B[nnz]       = {1.0, 6.0, 2.0, 4.0, 5.0, 3.0, 7.0, 8.0}; // device memory
        C[ldc * n]           = {15.0, 20.0, 16.0, 21.0, 17.0, 22.0,      // device memory
                                18.0, 23.0, 19.0, 24.0};

        // alpha and beta
        float alpha = 1.0f;
        float beta  = 0.0f;

        // Perform the matrix multiplication
        rocsparse_sgemmi(handle,
                         rocsparse_operation_none,
                         rocsparse_operation_transpose,
                         m,
                         n,
                         k,
                         nnz,
                         &alpha,
                         A,
                         lda,
                         descr_B,
                         csc_val_B,
                         csc_col_ptr_B,
                         csc_row_ind_B,
                         &beta,
                         C,
                         ldc);

  Note

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

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - trans_A – [in] matrix \(A\) operation type.

    - trans_B – [in] matrix \(B\) operation type.

    - m – [in] number of rows of the dense matrix \(A\).

    - n – [in] number of columns of the sparse CSR matrix \(op(B)\) and \(C\).

    - k – [in] number of columns of the dense matrix \(A\).

    - nnz – [in] number of non-zero entries of the sparse CSR matrix \(B\).

    - alpha – [in] scalar \(\alpha\).

    - A – [in] array of dimension \(lda \times k\) ( \(op(A) == A\)) or \(lda \times m\) ( \(op(A) == A^T\) or \(op(A) == A^H\)).

    - lda – [in] leading dimension of \(A\), must be at least \(m\) ( \(op(A) == A\)) or \(k\) ( \(op(A) == A^T\) or \(op(A) == A^H\)).

    - descr – [in] descriptor of the sparse CSR matrix \(B\). Currently, only rocsparse_matrix_type_general is supported.

    - csr_val – [in] array of `nnz` elements of the sparse CSR matrix \(B\).

    - csr_row_ptr – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix \(B\).

    - csr_col_ind – [in] array of `nnz` elements containing the column indices of the sparse CSR matrix \(B\).

    - beta – [in] scalar \(\beta\).

    - C – [inout] array of dimension \(ldc \times n\) that holds the values of \(C\).

    - ldc – [in] leading dimension of \(C\), must be at least \(m\).

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m`, `n`, `k`, `nnz`, `lda` or `ldc` is invalid.

    - rocsparse_status_invalid_pointer – `alpha`, `A`, `csr_val`, `csr_row_ptr`, `csr_col_ind`, `beta` or `C` pointer is invalid.

## Sparse Extra Functions

This module holds all sparse extra routines.

The sparse extra routines describe operations that manipulate sparse matrices.

The routines in this module do not support execution in a hipGraph context.

### rocsparse_bsrgeam_nnzb()

rocsparse_status rocsparse_bsrgeam_nnzb(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, rocsparse_int block_dim, const rocsparse_mat_descr descr_A, rocsparse_int nnzb_A, const rocsparse_int *bsr_row_ptr_A, const rocsparse_int *bsr_col_ind_A, const rocsparse_mat_descr descr_B, rocsparse_int nnzb_B, const rocsparse_int *bsr_row_ptr_B, const rocsparse_int *bsr_col_ind_B, const rocsparse_mat_descr descr_C, rocsparse_int *bsr_row_ptr_C, rocsparse_int *nnzb_C)

  Sparse matrix sparse matrix addition using BSR storage format.

  `rocsparse_bsrgeam_nnz` computes the total BSR non-zero elements and the BSR row offsets, that point to the start of every row of the sparse BSR matrix, of the resulting matrix C. It is assumed that `bsr_row_ptr_C` has been allocated with size `mb+1`.

  Note

  This function is blocking with respect to the host.

  Note

  Currently, only rocsparse_matrix_type_general is supported.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - dir – [in] direction that specifies whether to count nonzero elements by rocsparse_direction_row or by rocsparse_direction_row in the BSR matrices \(A\), \(B\), and \(C\).

    - mb – [in] number of block rows in the sparse BSR matrix \(op(A)\) and \(C\).

    - nb – [in] number of block columns of the sparse BSR matrix \(op(B)\) and \(C\).

    - block_dim – [in] the block dimension of the BSR matrix \(A\). Between 1 and m where `m=mb*block_dim`.

    - descr_A – [in] descriptor of the sparse BSR matrix \(A\). Currenty, only rocsparse_matrix_type_general is supported.

    - nnzb_A – [in] number of non-zero block entries of the sparse BSR matrix \(A\).

    - bsr_row_ptr_A – [in] array of `mb+1` elements that point to the start of every block row of the sparse BSR matrix \(A\).

    - bsr_col_ind_A – [in] array of `nnzb_A` elements containing the column indices of the sparse BSR matrix \(A\).

    - descr_B – [in] descriptor of the sparse BSR matrix \(B\). Currenty, only rocsparse_matrix_type_general is supported.

    - nnzb_B – [in] number of non-zero block entries of the sparse BSR matrix \(B\).

    - bsr_row_ptr_B – [in] array of `mb+1` elements that point to the start of every block row of the sparse BSR matrix \(B\).

    - bsr_col_ind_B – [in] array of `nnzb_B` elements containing the block column indices of the sparse BSR matrix \(B\).

    - descr_C – [in] descriptor of the sparse BSR matrix \(C\). Currenty, only rocsparse_matrix_type_general is supported.

    - bsr_row_ptr_C – [out] array of `mb+1` elements that point to the start of every block row of the sparse BSR matrix \(C\).

    - nnzb_C – [out] pointer to the number of non-zero block entries of the sparse BSR matrix \(C\). `nnzb_C` can be a host or device pointer.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `mb`, `nb`, `kb`, `nnzb_A` or `nnzb_B` is invalid.

    - rocsparse_status_invalid_pointer – `descr_A`, `bsr_row_ptr_A`, `bsr_col_ind_A`, `descr_B`, `bsr_row_ptr_B`, `bsr_col_ind_B`, `descr_C`, `bsr_row_ptr_C` or `nnzb_C` is invalid.

    - rocsparse_status_not_implemented – `rocsparse_matrix_type` != rocsparse_matrix_type_general.

### rocsparse_bsrgeam()

rocsparse_status rocsparse_sbsrgeam(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, rocsparse_int block_dim, const float *alpha, const rocsparse_mat_descr descr_A, rocsparse_int nnzb_A, const float *bsr_val_A, const rocsparse_int *bsr_row_ptr_A, const rocsparse_int *bsr_col_ind_A, const float *beta, const rocsparse_mat_descr descr_B, rocsparse_int nnzb_B, const float *bsr_val_B, const rocsparse_int *bsr_row_ptr_B, const rocsparse_int *bsr_col_ind_B, const rocsparse_mat_descr descr_C, float *bsr_val_C, const rocsparse_int *bsr_row_ptr_C, rocsparse_int *bsr_col_ind_C)

rocsparse_status rocsparse_dbsrgeam(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, rocsparse_int block_dim, const double *alpha, const rocsparse_mat_descr descr_A, rocsparse_int nnzb_A, const double *bsr_val_A, const rocsparse_int *bsr_row_ptr_A, const rocsparse_int *bsr_col_ind_A, const double *beta, const rocsparse_mat_descr descr_B, rocsparse_int nnzb_B, const double *bsr_val_B, const rocsparse_int *bsr_row_ptr_B, const rocsparse_int *bsr_col_ind_B, const rocsparse_mat_descr descr_C, double *bsr_val_C, const rocsparse_int *bsr_row_ptr_C, rocsparse_int *bsr_col_ind_C)

rocsparse_status rocsparse_cbsrgeam(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, rocsparse_int block_dim, const rocsparse_float_complex *alpha, const rocsparse_mat_descr descr_A, rocsparse_int nnzb_A, const rocsparse_float_complex *bsr_val_A, const rocsparse_int *bsr_row_ptr_A, const rocsparse_int *bsr_col_ind_A, const rocsparse_float_complex *beta, const rocsparse_mat_descr descr_B, rocsparse_int nnzb_B, const rocsparse_float_complex *bsr_val_B, const rocsparse_int *bsr_row_ptr_B, const rocsparse_int *bsr_col_ind_B, const rocsparse_mat_descr descr_C, rocsparse_float_complex *bsr_val_C, const rocsparse_int *bsr_row_ptr_C, rocsparse_int *bsr_col_ind_C)

rocsparse_status rocsparse_zbsrgeam(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, rocsparse_int block_dim, const rocsparse_double_complex *alpha, const rocsparse_mat_descr descr_A, rocsparse_int nnzb_A, const rocsparse_double_complex *bsr_val_A, const rocsparse_int *bsr_row_ptr_A, const rocsparse_int *bsr_col_ind_A, const rocsparse_double_complex *beta, const rocsparse_mat_descr descr_B, rocsparse_int nnzb_B, const rocsparse_double_complex *bsr_val_B, const rocsparse_int *bsr_row_ptr_B, const rocsparse_int *bsr_col_ind_B, const rocsparse_mat_descr descr_C, rocsparse_double_complex *bsr_val_C, const rocsparse_int *bsr_row_ptr_C, rocsparse_int *bsr_col_ind_C)

  Sparse matrix sparse matrix addition using BSR storage format.

  `rocsparse_bsrgeam` multiplies the scalar \(\alpha\) with the sparse \(m \times n\) matrix \(A\), defined in BSR storage format, multiplies the scalar \(\beta\) with the sparse \(mb \times nb\) matrix \(B\), defined in BSR storage format, and adds both resulting matrices to obtain the sparse \(mb \times nb\) matrix \(C\), defined in BSR storage format, such that

  \[ C := \alpha \cdot A + \beta \cdot B. \]

  It is assumed that `bsr_row_ptr_C` has already been filled and that `bsr_val_C` and `bsr_col_ind_C` are allocated by the user. `bsr_row_ptr_C` and allocation size of `bsr_col_ind_C` and `bsr_val_C` is defined by the number of non-zero block elements of the sparse BSR matrix C. Both can be obtained by rocsparse_bsrgeam_nnz().

  Example

    This example adds two CSR matrices.

        // Initialize scalar multipliers
        float alpha = 1.0f;
        float beta  = 1.0f;

        // Create matrix descriptors
        rocsparse_mat_descr descr_A;
        rocsparse_mat_descr descr_B;
        rocsparse_mat_descr descr_C;

        rocsparse_create_mat_descr(&descr_A);
        rocsparse_create_mat_descr(&descr_B);
        rocsparse_create_mat_descr(&descr_C);

        // Set pointer mode
        rocsparse_set_pointer_mode(handle, rocsparse_pointer_mode_host);

        // Obtain number of total non-zero block entries in C and block row pointers of C
        rocsparse_int nnzb_C;
        hipMalloc((void**)&bsr_row_ptr_C, sizeof(rocsparse_int) * (mb + 1));

        rocsparse_bsrgeam_nnzb(handle,
                              dir,
                              mb,
                              nb,
                              block_dim,
                              descr_A,
                              nnzb_A,
                              bsr_row_ptr_A,
                              bsr_col_ind_A,
                              descr_B,
                              nnzb_B,
                              bsr_row_ptr_B,
                              bsr_col_ind_B,
                              descr_C,
                              bsr_row_ptr_C,
                              &nnzb_C);

        // Compute block column indices and block values of C
        hipMalloc((void**)&bsr_col_ind_C, sizeof(rocsparse_int) * nnzb_C);
        hipMalloc((void**)&bsr_val_C, sizeof(float) * nnzb_C * block_dim * block_dim);

        rocsparse_sbsrgeam(handle,
                           dir,
                           mb,
                           nb,
                           block_dim,
                           &alpha,
                           descr_A,
                           nnzb_A,
                           bsr_val_A,
                           bsr_row_ptr_A,
                           bsr_col_ind_A,
                           &beta,
                           descr_B,
                           nnzb_B,
                           bsr_val_B,
                           bsr_row_ptr_B,
                           bsr_col_ind_B,
                           descr_C,
                           bsr_val_C,
                           bsr_row_ptr_C,
                           bsr_col_ind_C);

  Note

  Both scalars \(\alpha\) and \(beta\) have to be valid.

  Note

  Currently, only rocsparse_matrix_type_general is supported.

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - dir – [in] direction that specifies whether to count nonzero elements by rocsparse_direction_row or by rocsparse_direction_row in the BSR matrices \(A\), \(B\), and \(C\).

    - mb – [in] number of rows of the sparse BSR matrix \(A\), \(B\) and \(C\).

    - nb – [in] number of columns of the sparse BSR matrix \(A\), \(B\) and \(C\).

    - block_dim – [in] the block dimension of the BSR matrix \(A\). Between 1 and m where `m=mb*block_dim`.

    - alpha – [in] scalar \(\alpha\).

    - descr_A – [in] descriptor of the sparse CSR matrix \(A\). Currenty, only rocsparse_matrix_type_general is supported.

    - nnzb_A – [in] number of non-zero block entries of the sparse BSR matrix \(A\).

    - bsr_val_A – [in] array of `nnzb_A` block elements of the sparse BSR matrix \(A\).

    - bsr_row_ptr_A – [in] array of `mb+1` block elements that point to the start of every block row of the sparse BSR matrix \(A\).

    - bsr_col_ind_A – [in] array of `nnzb_A` block elements containing the block column indices of the sparse BSR matrix \(A\).

    - beta – [in] scalar \(\beta\).

    - descr_B – [in] descriptor of the sparse BSR matrix \(B\). Currenty, only rocsparse_matrix_type_general is supported.

    - nnzb_B – [in] number of non-zero block entries of the sparse BSR matrix \(B\).

    - bsr_val_B – [in] array of `nnzb_B` block elements of the sparse BSR matrix \(B\).

    - bsr_row_ptr_B – [in] array of `mb+1` block elements that point to the start of every block row of the sparse BSR matrix \(B\).

    - bsr_col_ind_B – [in] array of `nnzb_B` block elements containing the block column indices of the sparse BSR matrix \(B\).

    - descr_C – [in] descriptor of the sparse BSR matrix \(C\). Currenty, only rocsparse_matrix_type_general is supported.

    - bsr_val_C – [out] array of block elements of the sparse BSR matrix \(C\).

    - bsr_row_ptr_C – [in] array of `mb+1` block elements that point to the start of every block row of the sparse BSR matrix \(C\).

    - bsr_col_ind_C – [out] array of block elements containing the block column indices of the sparse BSR matrix \(C\).

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `mb`, `nb`, `nnzb_A` or `nnzb_B` is invalid.

    - rocsparse_status_invalid_pointer – `alpha`, `descr_A`, `bsr_val_A`, `bsr_row_ptr_A`, `bsr_col_ind_A`, `beta`, `descr_B`, `bsr_val_B`, `bsr_row_ptr_B`, `bsr_col_ind_B`, `descr_C`, `csr_val_C`, `bsr_row_ptr_C` or `bsr_col_ind_C` is invalid.

    - rocsparse_status_not_implemented – `rocsparse_matrix_type` != rocsparse_matrix_type_general.

### rocsparse_bsrgemm_buffer_size()

rocsparse_status rocsparse_sbsrgemm_buffer_size(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int mb, rocsparse_int nb, rocsparse_int kb, rocsparse_int block_dim, const float *alpha, const rocsparse_mat_descr descr_A, rocsparse_int nnzb_A, const rocsparse_int *bsr_row_ptr_A, const rocsparse_int *bsr_col_ind_A, const rocsparse_mat_descr descr_B, rocsparse_int nnzb_B, const rocsparse_int *bsr_row_ptr_B, const rocsparse_int *bsr_col_ind_B, const float *beta, const rocsparse_mat_descr descr_D, rocsparse_int nnzb_D, const rocsparse_int *bsr_row_ptr_D, const rocsparse_int *bsr_col_ind_D, rocsparse_mat_info info_C, size_t *buffer_size)

rocsparse_status rocsparse_dbsrgemm_buffer_size(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int mb, rocsparse_int nb, rocsparse_int kb, rocsparse_int block_dim, const double *alpha, const rocsparse_mat_descr descr_A, rocsparse_int nnzb_A, const rocsparse_int *bsr_row_ptr_A, const rocsparse_int *bsr_col_ind_A, const rocsparse_mat_descr descr_B, rocsparse_int nnzb_B, const rocsparse_int *bsr_row_ptr_B, const rocsparse_int *bsr_col_ind_B, const double *beta, const rocsparse_mat_descr descr_D, rocsparse_int nnzb_D, const rocsparse_int *bsr_row_ptr_D, const rocsparse_int *bsr_col_ind_D, rocsparse_mat_info info_C, size_t *buffer_size)

rocsparse_status rocsparse_cbsrgemm_buffer_size(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int mb, rocsparse_int nb, rocsparse_int kb, rocsparse_int block_dim, const rocsparse_float_complex *alpha, const rocsparse_mat_descr descr_A, rocsparse_int nnzb_A, const rocsparse_int *bsr_row_ptr_A, const rocsparse_int *bsr_col_ind_A, const rocsparse_mat_descr descr_B, rocsparse_int nnzb_B, const rocsparse_int *bsr_row_ptr_B, const rocsparse_int *bsr_col_ind_B, const rocsparse_float_complex *beta, const rocsparse_mat_descr descr_D, rocsparse_int nnzb_D, const rocsparse_int *bsr_row_ptr_D, const rocsparse_int *bsr_col_ind_D, rocsparse_mat_info info_C, size_t *buffer_size)

rocsparse_status rocsparse_zbsrgemm_buffer_size(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int mb, rocsparse_int nb, rocsparse_int kb, rocsparse_int block_dim, const rocsparse_double_complex *alpha, const rocsparse_mat_descr descr_A, rocsparse_int nnzb_A, const rocsparse_int *bsr_row_ptr_A, const rocsparse_int *bsr_col_ind_A, const rocsparse_mat_descr descr_B, rocsparse_int nnzb_B, const rocsparse_int *bsr_row_ptr_B, const rocsparse_int *bsr_col_ind_B, const rocsparse_double_complex *beta, const rocsparse_mat_descr descr_D, rocsparse_int nnzb_D, const rocsparse_int *bsr_row_ptr_D, const rocsparse_int *bsr_col_ind_D, rocsparse_mat_info info_C, size_t *buffer_size)

  Sparse matrix sparse matrix multiplication using BSR storage format.

  `rocsparse_bsrgemm_buffer_size` returns the size of the temporary storage buffer that is required by rocsparse_bsrgemm_nnzb(), rocsparse_sbsrgemm(), rocsparse_dbsrgemm(), rocsparse_cbsrgemm() and rocsparse_zbsrgemm(). The temporary storage buffer must be allocated by the user.

  Note

  This function is blocking with respect to the host.

  Note

  Currently, only `trans_A` == `trans_B` == rocsparse_operation_none is supported.

  Note

  Currently, only rocsparse_matrix_type_general is supported.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - dir – [in] direction that specifies whether to count nonzero elements by rocsparse_direction_row or by rocsparse_direction_row in the BSR matrices \(A\), \(B\), \(C\), and \(D\).

    - trans_A – [in] matrix \(A\) operation type.

    - trans_B – [in] matrix \(B\) operation type.

    - mb – [in] number of block rows in the sparse BSR matrix \(op(A)\) and \(C\).

    - nb – [in] number of block columns of the sparse BSR matrix \(op(B)\) and \(C\).

    - kb – [in] number of block columns of the sparse BSR matrix \(op(A)\) and number of rows of the sparse BSR matrix \(op(B)\).

    - block_dim – [in] the block dimension of the BSR matrix \(A\), \(B\), \(C\), and \(D\).

    - alpha – [in] scalar \(\alpha\).

    - descr_A – [in] descriptor of the sparse BSR matrix \(A\). Currenty, only rocsparse_matrix_type_general is supported.

    - nnzb_A – [in] number of non-zero block entries of the sparse BSR matrix \(A\).

    - bsr_row_ptr_A – [in] array of `mb+1` elements ( \(op(A) == A\), `kb+1` otherwise) that point to the start of every block row of the sparse BSR matrix \(op(A)\).

    - bsr_col_ind_A – [in] array of `nnzb_A` elements containing the block column indices of the sparse BSR matrix \(A\).

    - descr_B – [in] descriptor of the sparse BSR matrix \(B\). Currenty, only rocsparse_matrix_type_general is supported.

    - nnzb_B – [in] number of non-zero block entries of the sparse BSR matrix \(B\).

    - bsr_row_ptr_B – [in] array of `kb+1` elements ( \(op(B) == B\), `mb+1` otherwise) that point to the start of every block row of the sparse BSR matrix \(op(B)\).

    - bsr_col_ind_B – [in] array of `nnzb_B` elements containing the block column indices of the sparse BSR matrix \(B\).

    - beta – [in] scalar \(\beta\).

    - descr_D – [in] descriptor of the sparse BSR matrix \(D\). Currenty, only rocsparse_matrix_type_general is supported.

    - nnzb_D – [in] number of non-zero block entries of the sparse BSR matrix \(D\).

    - bsr_row_ptr_D – [in] array of `mb+1` elements that point to the start of every block row of the sparse BSR matrix \(D\).

    - bsr_col_ind_D – [in] array of `nnzb_D` elements containing the block column indices of the sparse BSR matrix \(D\).

    - info_C – [inout] structure that holds meta data for the sparse BSR matrix \(C\).

    - buffer_size – [out] number of bytes of the temporary storage buffer required by rocsparse_bsrgemm_nnzb(), rocsparse_sbsrgemm(), rocsparse_dbsrgemm(), rocsparse_cbsrgemm() and rocsparse_zbsrgemm().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `mb`, `nb`, `kb`, `block_dim`, `nnzb_A`, `nnzb_B` or `nnzb_D` is invalid.

    - rocsparse_status_invalid_pointer – `alpha` and `beta` are invalid, `descr_A`, `bsr_row_ptr_A`, `bsr_col_ind_A`, `descr_B`, `bsr_row_ptr_B` or `bsr_col_ind_B` are invalid if `alpha` is valid, `descr_D`, `bsr_row_ptr_D` or `bsr_col_ind_D` is invalid if `beta` is valid, `info_C` or `buffer_size` is invalid.

    - rocsparse_status_not_implemented – `trans_A` != rocsparse_operation_none, `trans_B` != rocsparse_operation_none, or `rocsparse_matrix_type` != rocsparse_matrix_type_general.

### rocsparse_bsrgemm_nnzb()

rocsparse_status rocsparse_bsrgemm_nnzb(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int mb, rocsparse_int nb, rocsparse_int kb, rocsparse_int block_dim, const rocsparse_mat_descr descr_A, rocsparse_int nnzb_A, const rocsparse_int *bsr_row_ptr_A, const rocsparse_int *bsr_col_ind_A, const rocsparse_mat_descr descr_B, rocsparse_int nnzb_B, const rocsparse_int *bsr_row_ptr_B, const rocsparse_int *bsr_col_ind_B, const rocsparse_mat_descr descr_D, rocsparse_int nnzb_D, const rocsparse_int *bsr_row_ptr_D, const rocsparse_int *bsr_col_ind_D, const rocsparse_mat_descr descr_C, rocsparse_int *bsr_row_ptr_C, rocsparse_int *nnzb_C, const rocsparse_mat_info info_C, void *temp_buffer)

  Sparse matrix sparse matrix multiplication using BSR storage format.

  `rocsparse_bsrgemm_nnzb` computes the total BSR non-zero block elements and the BSR block row offsets, that point to the start of every block row of the sparse BSR matrix, of the resulting multiplied matrix C. It is assumed that `bsr_row_ptr_C` has been allocated with size `mb+1`. The required buffer size can be obtained by rocsparse_sbsrgemm_buffer_size(), rocsparse_dbsrgemm_buffer_size(), rocsparse_cbsrgemm_buffer_size() and rocsparse_zbsrgemm_buffer_size(), respectively.

  Note

  This function is blocking with respect to the host.

  Note

  Currently, only `trans_A` == `trans_B` == rocsparse_operation_none is supported.

  Note

  Currently, only rocsparse_matrix_type_general is supported.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - dir – [in] direction that specifies whether to count nonzero elements by rocsparse_direction_row or by rocsparse_direction_row in the BSR matrices \(A\), \(B\), \(C\), and \(D\).

    - trans_A – [in] matrix \(A\) operation type.

    - trans_B – [in] matrix \(B\) operation type.

    - mb – [in] number of block rows in the sparse BSR matrix \(op(A)\) and \(C\).

    - nb – [in] number of block columns of the sparse BSR matrix \(op(B)\) and \(C\).

    - kb – [in] number of block columns of the sparse BSR matrix \(op(A)\) and number of rows of the sparse BSR matrix \(op(B)\).

    - block_dim – [in] the block dimension of the BSR matrix \(A\), \(B\), \(C\), and \(D\).

    - descr_A – [in] descriptor of the sparse BSR matrix \(A\). Currenty, only rocsparse_matrix_type_general is supported.

    - nnzb_A – [in] number of non-zero block entries of the sparse BSR matrix \(A\).

    - bsr_row_ptr_A – [in] array of `mb+1` block elements ( \(op(A) == A\), `kb+1` otherwise) that point to the start of every row of the sparse BSR matrix \(op(A)\).

    - bsr_col_ind_A – [in] array of `nnzb_A` block elements containing the block column indices of the sparse BSR matrix \(A\).

    - descr_B – [in] descriptor of the sparse BSR matrix \(B\). Currenty, only rocsparse_matrix_type_general is supported.

    - nnzb_B – [in] number of non-zero block entries of the sparse BSR matrix \(B\).

    - bsr_row_ptr_B – [in] array of `kb+1` block elements ( \(op(B) == B\), `mb+1` otherwise) that point to the start of every block row of the sparse BSR matrix \(op(B)\).

    - bsr_col_ind_B – [in] array of `nnzb_B` block elements containing the block column indices of the sparse BSR matrix \(B\).

    - descr_D – [in] descriptor of the sparse BSR matrix \(D\). Currenty, only rocsparse_matrix_type_general is supported.

    - nnzb_D – [in] number of non-zero block entries of the sparse BSR matrix \(D\).

    - bsr_row_ptr_D – [in] array of `mb+1` block elements that point to the start of every block row of the sparse BSR matrix \(D\).

    - bsr_col_ind_D – [in] array of `nnzb_D` block elements containing the block column indices of the sparse BSR matrix \(D\).

    - descr_C – [in] descriptor of the sparse BSR matrix \(C\). Currenty, only rocsparse_matrix_type_general is supported.

    - bsr_row_ptr_C – [out] array of `mb+1` block elements that point to the start of every block row of the sparse BSR matrix \(C\).

    - nnzb_C – [out] pointer to the number of non-zero block entries of the sparse BSR matrix \(C\).

    - info_C – [in] structure that holds meta data for the sparse BSR matrix \(C\).

    - temp_buffer – [in] temporary storage buffer allocated by the user, size is returned by rocsparse_sbsrgemm_buffer_size(), rocsparse_dbsrgemm_buffer_size(), rocsparse_cbsrgemm_buffer_size() or rocsparse_zbsrgemm_buffer_size().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `mb`, `nb`, `kb`, `block_dim`, `nnzb_A`, `nnzb_B` or `nnzb_D` is invalid.

    - rocsparse_status_invalid_pointer – `descr_A`, `bsr_row_ptr_A`, `bsr_col_ind_A`, `descr_B`, `bsr_row_ptr_B`, `bsr_col_ind_B`, `descr_D`, `bsr_row_ptr_D`, `bsr_col_ind_D`, `descr_C`, `bsr_row_ptr_C`, `nnzb_C`, `info_C` or `temp_buffer` is invalid.

    - rocsparse_status_memory_error – additional buffer for long rows could not be allocated.

    - rocsparse_status_not_implemented – `trans_A` != rocsparse_operation_none, `trans_B` != rocsparse_operation_none, or `rocsparse_matrix_type` != rocsparse_matrix_type_general.

### rocsparse_bsrgemm()

rocsparse_status rocsparse_sbsrgemm(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int mb, rocsparse_int nb, rocsparse_int kb, rocsparse_int block_dim, const float *alpha, const rocsparse_mat_descr descr_A, rocsparse_int nnzb_A, const float *bsr_val_A, const rocsparse_int *bsr_row_ptr_A, const rocsparse_int *bsr_col_ind_A, const rocsparse_mat_descr descr_B, rocsparse_int nnzb_B, const float *bsr_val_B, const rocsparse_int *bsr_row_ptr_B, const rocsparse_int *bsr_col_ind_B, const float *beta, const rocsparse_mat_descr descr_D, rocsparse_int nnzb_D, const float *bsr_val_D, const rocsparse_int *bsr_row_ptr_D, const rocsparse_int *bsr_col_ind_D, const rocsparse_mat_descr descr_C, float *bsr_val_C, const rocsparse_int *bsr_row_ptr_C, rocsparse_int *bsr_col_ind_C, const rocsparse_mat_info info_C, void *temp_buffer)

rocsparse_status rocsparse_dbsrgemm(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int mb, rocsparse_int nb, rocsparse_int kb, rocsparse_int block_dim, const double *alpha, const rocsparse_mat_descr descr_A, rocsparse_int nnzb_A, const double *bsr_val_A, const rocsparse_int *bsr_row_ptr_A, const rocsparse_int *bsr_col_ind_A, const rocsparse_mat_descr descr_B, rocsparse_int nnzb_B, const double *bsr_val_B, const rocsparse_int *bsr_row_ptr_B, const rocsparse_int *bsr_col_ind_B, const double *beta, const rocsparse_mat_descr descr_D, rocsparse_int nnzb_D, const double *bsr_val_D, const rocsparse_int *bsr_row_ptr_D, const rocsparse_int *bsr_col_ind_D, const rocsparse_mat_descr descr_C, double *bsr_val_C, const rocsparse_int *bsr_row_ptr_C, rocsparse_int *bsr_col_ind_C, const rocsparse_mat_info info_C, void *temp_buffer)

rocsparse_status rocsparse_cbsrgemm(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int mb, rocsparse_int nb, rocsparse_int kb, rocsparse_int block_dim, const rocsparse_float_complex *alpha, const rocsparse_mat_descr descr_A, rocsparse_int nnzb_A, const rocsparse_float_complex *bsr_val_A, const rocsparse_int *bsr_row_ptr_A, const rocsparse_int *bsr_col_ind_A, const rocsparse_mat_descr descr_B, rocsparse_int nnzb_B, const rocsparse_float_complex *bsr_val_B, const rocsparse_int *bsr_row_ptr_B, const rocsparse_int *bsr_col_ind_B, const rocsparse_float_complex *beta, const rocsparse_mat_descr descr_D, rocsparse_int nnzb_D, const rocsparse_float_complex *bsr_val_D, const rocsparse_int *bsr_row_ptr_D, const rocsparse_int *bsr_col_ind_D, const rocsparse_mat_descr descr_C, rocsparse_float_complex *bsr_val_C, const rocsparse_int *bsr_row_ptr_C, rocsparse_int *bsr_col_ind_C, const rocsparse_mat_info info_C, void *temp_buffer)

rocsparse_status rocsparse_zbsrgemm(rocsparse_handle handle, rocsparse_direction dir, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int mb, rocsparse_int nb, rocsparse_int kb, rocsparse_int block_dim, const rocsparse_double_complex *alpha, const rocsparse_mat_descr descr_A, rocsparse_int nnzb_A, const rocsparse_double_complex *bsr_val_A, const rocsparse_int *bsr_row_ptr_A, const rocsparse_int *bsr_col_ind_A, const rocsparse_mat_descr descr_B, rocsparse_int nnzb_B, const rocsparse_double_complex *bsr_val_B, const rocsparse_int *bsr_row_ptr_B, const rocsparse_int *bsr_col_ind_B, const rocsparse_double_complex *beta, const rocsparse_mat_descr descr_D, rocsparse_int nnzb_D, const rocsparse_double_complex *bsr_val_D, const rocsparse_int *bsr_row_ptr_D, const rocsparse_int *bsr_col_ind_D, const rocsparse_mat_descr descr_C, rocsparse_double_complex *bsr_val_C, const rocsparse_int *bsr_row_ptr_C, rocsparse_int *bsr_col_ind_C, const rocsparse_mat_info info_C, void *temp_buffer)

  Sparse matrix sparse matrix multiplication using BSR storage format.

  `rocsparse_bsrgemm` multiplies the scalar \(\alpha\) with the sparse \(mb \times kb\) matrix \(A\), defined in BSR storage format, and the sparse \(kb \times nb\) matrix \(B\), defined in BSR storage format, and adds the result to the sparse \(mb \times nb\) matrix \(D\) that is multiplied by \(\beta\). The final result is stored in the sparse \(mb \times nb\) matrix \(C\), defined in BSR storage format, such that

  \[ C := \alpha \cdot op(A) \cdot op(B) + \beta \cdot D, \]
  with
  \[\begin{split} op(A) = \left\{ \begin{array}{ll} A, & \text{if trans_A == rocsparse_operation_none} \\ A^T, & \text{if trans_A == rocsparse_operation_transpose} \\ A^H, & \text{if trans_A == rocsparse_operation_conjugate_transpose} \end{array} \right. \end{split}\]
  and
  \[\begin{split} op(B) = \left\{ \begin{array}{ll} B, & \text{if trans_B == rocsparse_operation_none} \\ B^T, & \text{if trans_B == rocsparse_operation_transpose} \\ B^H, & \text{if trans_B == rocsparse_operation_conjugate_transpose} \end{array} \right. \end{split}\]

  It is assumed that `bsr_row_ptr_C` has already been filled and that `bsr_val_C` and `bsr_col_ind_C` are allocated by the user. `bsr_row_ptr_C` and allocation size of `bsr_col_ind_C` and `bsr_val_C` is defined by the number of non-zero elements of the sparse BSR matrix C. Both can be obtained by rocsparse_bsrgemm_nnzb(). The required buffer size for the computation can be obtained by rocsparse_sbsrgemm_buffer_size(), rocsparse_dbsrgemm_buffer_size(), rocsparse_cbsrgemm_buffer_size() and rocsparse_zbsrgemm_buffer_size(), respectively.

  Example

    This example multiplies two BSR matrices with a scalar alpha and adds the result to another BSR matrix.

        // Initialize scalar multipliers
        float alpha = 2.0f;
        float beta  = 1.0f;

        // Create matrix descriptors
        rocsparse_mat_descr descr_A;
        rocsparse_mat_descr descr_B;
        rocsparse_mat_descr descr_C;
        rocsparse_mat_descr descr_D;

        rocsparse_create_mat_descr(&descr_A);
        rocsparse_create_mat_descr(&descr_B);
        rocsparse_create_mat_descr(&descr_C);
        rocsparse_create_mat_descr(&descr_D);

        // Create matrix info structure
        rocsparse_mat_info info_C;
        rocsparse_create_mat_info(&info_C);

        // Set pointer mode
        rocsparse_set_pointer_mode(handle, rocsparse_pointer_mode_host);

        // Query rocsparse for the required buffer size
        size_t buffer_size;

        rocsparse_sbsrgemm_buffer_size(handle,
                                       rocsparse_direction_row,
                                       rocsparse_operation_none,
                                       rocsparse_operation_none,
                                       mb,
                                       nb,
                                       kb,
                                       block_dim,
                                       &alpha,
                                       descr_A,
                                       nnzb_A,
                                       bsr_row_ptr_A,
                                       bsr_col_ind_A,
                                       descr_B,
                                       nnzb_B,
                                       bsr_row_ptr_B,
                                       bsr_col_ind_B,
                                       &beta,
                                       descr_D,
                                       nnzb_D,
                                       bsr_row_ptr_D,
                                       bsr_col_ind_D,
                                       info_C,
                                       &buffer_size);

        // Allocate buffer
        void* buffer;
        hipMalloc(&buffer, buffer_size);

        // Obtain number of total non-zero block entries in C and block row pointers of C
        rocsparse_int nnzb_C;
        hipMalloc((void**)&bsr_row_ptr_C, sizeof(rocsparse_int) * (mb + 1));

        rocsparse_bsrgemm_nnzb(handle,
                              rocsparse_direction_row,
                              rocsparse_operation_none,
                              rocsparse_operation_none,
                              mb,
                              nb,
                              kb,
                              block_dim,
                              descr_A,
                              nnzb_A,
                              bsr_row_ptr_A,
                              bsr_col_ind_A,
                              descr_B,
                              nnzb_B,
                              bsr_row_ptr_B,
                              bsr_col_ind_B,
                              descr_D,
                              nnzb_D,
                              bsr_row_ptr_D,
                              bsr_col_ind_D,
                              descr_C,
                              bsr_row_ptr_C,
                              &nnzb_C,
                              info_C,
                              buffer);

        // Compute block column indices and values of C
        hipMalloc((void**)&bsr_col_ind_C, sizeof(rocsparse_int) * nnzb_C);
        hipMalloc((void**)&bsr_val_C, sizeof(float) * block_dim * block_dim *nnzb_C);

        rocsparse_sbsrgemm(handle,
                           rocsparse_direction_row,
                           rocsparse_operation_none,
                           rocsparse_operation_none,
                           mb,
                           nb,
                           kb,
                           block_dim,
                           &alpha,
                           descr_A,
                           nnzb_A,
                           bsr_val_A,
                           bsr_row_ptr_A,
                           bsr_col_ind_A,
                           descr_B,
                           nnzb_B,
                           bsr_val_B,
                           bsr_row_ptr_B,
                           bsr_col_ind_B,
                           &beta,
                           descr_D,
                           nnzb_D,
                           bsr_val_D,
                           bsr_row_ptr_D,
                           bsr_col_ind_D,
                           descr_C,
                           bsr_val_C,
                           bsr_row_ptr_C,
                           bsr_col_ind_C,
                           info_C,
                           buffer);

  Note

  If \(\alpha == 0\), then \(C = \beta \cdot D\) will be computed.

  Note

  If \(\beta == 0\), then \(C = \alpha \cdot op(A) \cdot op(B)\) will be computed.

  Note

  \(\alpha == beta == 0\) is invalid.

  Note

  Currently, only `trans_A` == rocsparse_operation_none is supported.

  Note

  Currently, only `trans_B` == rocsparse_operation_none is supported.

  Note

  Currently, only rocsparse_matrix_type_general is supported.

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - dir – [in] direction that specifies whether to count nonzero elements by rocsparse_direction_row or by rocsparse_direction_row in the BSR matrices \(A\), \(B\), \(C\), and \(D\).

    - trans_A – [in] matrix \(A\) operation type.

    - trans_B – [in] matrix \(B\) operation type.

    - mb – [in] number of block rows of the sparse BSR matrix \(op(A)\) and \(C\).

    - nb – [in] number of block columns of the sparse BSR matrix \(op(B)\) and \(C\).

    - kb – [in] number of block columns of the sparse BSR matrix \(op(A)\) and number of block rows of the sparse BSR matrix \(op(B)\).

    - block_dim – [in] the block dimension of the BSR matrix \(A\), \(B\), \(C\), and \(D\).

    - alpha – [in] scalar \(\alpha\).

    - descr_A – [in] descriptor of the sparse BSR matrix \(A\). Currenty, only rocsparse_matrix_type_general is supported.

    - nnzb_A – [in] number of non-zero block entries of the sparse BSR matrix \(A\).

    - bsr_val_A – [in] array of `nnzb_A` block elements of the sparse BSR matrix \(A\).

    - bsr_row_ptr_A – [in] array of `mb+1` block elements ( \(op(A) == A\), `kb+1` otherwise) that point to the start of every block row of the sparse BSR matrix \(op(A)\).

    - bsr_col_ind_A – [in] array of `nnzb_A` block elements containing the block column indices of the sparse BSR matrix \(A\).

    - descr_B – [in] descriptor of the sparse BSR matrix \(B\). Currenty, only rocsparse_matrix_type_general is supported.

    - nnzb_B – [in] number of non-zero block entries of the sparse BSR matrix \(B\).

    - bsr_val_B – [in] array of `nnzb_B` block elements of the sparse BSR matrix \(B\).

    - bsr_row_ptr_B – [in] array of `kb+1` block elements ( \(op(B) == B\), `mb+1` otherwise) that point to the start of every block row of the sparse BSR matrix \(op(B)\).

    - bsr_col_ind_B – [in] array of `nnzb_B` block elements containing the block column indices of the sparse BSR matrix \(B\).

    - beta – [in] scalar \(\beta\).

    - descr_D – [in] descriptor of the sparse BSR matrix \(D\). Currenty, only rocsparse_matrix_type_general is supported.

    - nnzb_D – [in] number of non-zero block entries of the sparse BSR matrix \(D\).

    - bsr_val_D – [in] array of `nnzb_D` block elements of the sparse BSR matrix \(D\).

    - bsr_row_ptr_D – [in] array of `mb+1` block elements that point to the start of every block row of the sparse BSR matrix \(D\).

    - bsr_col_ind_D – [in] array of `nnzb_D` block elements containing the block column indices of the sparse BSR matrix \(D\).

    - descr_C – [in] descriptor of the sparse BSR matrix \(C\). Currenty, only rocsparse_matrix_type_general is supported.

    - bsr_val_C – [out] array of `nnzb_C` elements of the sparse BSR matrix \(C\).

    - bsr_row_ptr_C – [in] array of `mb+1` block elements that point to the start of every block row of the sparse BSR matrix \(C\).

    - bsr_col_ind_C – [out] array of `nnzb_C` block elements containing the block column indices of the sparse BSR matrix \(C\).

    - info_C – [in] structure that holds meta data for the sparse BSR matrix \(C\).

    - temp_buffer – [in] temporary storage buffer allocated by the user, size is returned by rocsparse_sbsrgemm_buffer_size(), rocsparse_dbsrgemm_buffer_size(), rocsparse_cbsrgemm_buffer_size() or rocsparse_zbsrgemm_buffer_size().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `mb`, `nb`, `kb`, `block_dim`, `nnzb_A`, `nnzb_B` or `nnzb_D` is invalid.

    - rocsparse_status_invalid_pointer – `alpha` and `beta` are invalid, `descr_A`, `bsr_val_A`, `bsr_row_ptr_A`, `bsr_col_ind_A`, `descr_B`, `bsr_val_B`, `bsr_row_ptr_B` or `bsr_col_ind_B` are invalid if `alpha` is valid, `descr_D`, `bsr_val_D`, `bsr_row_ptr_D` or `bsr_col_ind_D` is invalid if `beta` is valid, `bsr_val_C`, `bsr_row_ptr_C`, `bsr_col_ind_C`, `info_C` or `temp_buffer` is invalid.

    - rocsparse_status_memory_error – additional buffer for long rows could not be allocated.

    - rocsparse_status_not_implemented – `trans_A` != rocsparse_operation_none, `trans_B` != rocsparse_operation_none, or `rocsparse_matrix_type` != rocsparse_matrix_type_general.

### rocsparse_csrgeam_nnz()

rocsparse_status rocsparse_csrgeam_nnz(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr_A, rocsparse_int nnz_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, const rocsparse_mat_descr descr_B, rocsparse_int nnz_B, const rocsparse_int *csr_row_ptr_B, const rocsparse_int *csr_col_ind_B, const rocsparse_mat_descr descr_C, rocsparse_int *csr_row_ptr_C, rocsparse_int *nnz_C)

  Sparse matrix sparse matrix addition using CSR storage format.

  `rocsparse_csrgeam_nnz` computes the total CSR non-zero elements and the CSR row offsets, that point to the start of every row of the sparse CSR matrix, of the resulting matrix C. It is assumed that `csr_row_ptr_C` has been allocated with size `m+1`.

  Note

  This function is blocking with respect to the host.

  Note

  Currently, only rocsparse_matrix_type_general is supported.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows of the sparse CSR matrix \(A\), \(B\) and \(C\).

    - n – [in] number of columns of the sparse CSR matrix \(A\), \(B\) and \(C\).

    - descr_A – [in] descriptor of the sparse CSR matrix \(A\). Currenty, only rocsparse_matrix_type_general is supported.

    - nnz_A – [in] number of non-zero entries of the sparse CSR matrix \(A\).

    - csr_row_ptr_A – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix \(A\).

    - csr_col_ind_A – [in] array of `nnz_A` elements containing the column indices of the sparse CSR matrix \(A\).

    - descr_B – [in] descriptor of the sparse CSR matrix \(B\). Currenty, only rocsparse_matrix_type_general is supported.

    - nnz_B – [in] number of non-zero entries of the sparse CSR matrix \(B\).

    - csr_row_ptr_B – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix \(B\).

    - csr_col_ind_B – [in] array of `nnz_B` elements containing the column indices of the sparse CSR matrix \(B\).

    - descr_C – [in] descriptor of the sparse CSR matrix \(C\). Currenty, only rocsparse_matrix_type_general is supported.

    - csr_row_ptr_C – [out] array of `m+1` elements that point to the start of every row of the sparse CSR matrix \(C\).

    - nnz_C – [out] pointer to the number of non-zero entries of the sparse CSR matrix \(C\). `nnz_C` can be a host or device pointer.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m`, `n`, `nnz_A` or `nnz_B` is invalid.

    - rocsparse_status_invalid_pointer – `descr_A`, `csr_row_ptr_A`, `csr_col_ind_A`, `descr_B`, `csr_row_ptr_B`, `csr_col_ind_B`, `descr_C`, `csr_row_ptr_C` or `nnz_C` is invalid.

    - rocsparse_status_not_implemented – `rocsparse_matrix_type` != rocsparse_matrix_type_general.

### rocsparse_csrgeam()

rocsparse_status rocsparse_scsrgeam(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const float *alpha, const rocsparse_mat_descr descr_A, rocsparse_int nnz_A, const float *csr_val_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, const float *beta, const rocsparse_mat_descr descr_B, rocsparse_int nnz_B, const float *csr_val_B, const rocsparse_int *csr_row_ptr_B, const rocsparse_int *csr_col_ind_B, const rocsparse_mat_descr descr_C, float *csr_val_C, const rocsparse_int *csr_row_ptr_C, rocsparse_int *csr_col_ind_C)

rocsparse_status rocsparse_dcsrgeam(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const double *alpha, const rocsparse_mat_descr descr_A, rocsparse_int nnz_A, const double *csr_val_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, const double *beta, const rocsparse_mat_descr descr_B, rocsparse_int nnz_B, const double *csr_val_B, const rocsparse_int *csr_row_ptr_B, const rocsparse_int *csr_col_ind_B, const rocsparse_mat_descr descr_C, double *csr_val_C, const rocsparse_int *csr_row_ptr_C, rocsparse_int *csr_col_ind_C)

rocsparse_status rocsparse_ccsrgeam(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_float_complex *alpha, const rocsparse_mat_descr descr_A, rocsparse_int nnz_A, const rocsparse_float_complex *csr_val_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, const rocsparse_float_complex *beta, const rocsparse_mat_descr descr_B, rocsparse_int nnz_B, const rocsparse_float_complex *csr_val_B, const rocsparse_int *csr_row_ptr_B, const rocsparse_int *csr_col_ind_B, const rocsparse_mat_descr descr_C, rocsparse_float_complex *csr_val_C, const rocsparse_int *csr_row_ptr_C, rocsparse_int *csr_col_ind_C)

rocsparse_status rocsparse_zcsrgeam(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_double_complex *alpha, const rocsparse_mat_descr descr_A, rocsparse_int nnz_A, const rocsparse_double_complex *csr_val_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, const rocsparse_double_complex *beta, const rocsparse_mat_descr descr_B, rocsparse_int nnz_B, const rocsparse_double_complex *csr_val_B, const rocsparse_int *csr_row_ptr_B, const rocsparse_int *csr_col_ind_B, const rocsparse_mat_descr descr_C, rocsparse_double_complex *csr_val_C, const rocsparse_int *csr_row_ptr_C, rocsparse_int *csr_col_ind_C)

  Sparse matrix sparse matrix addition using CSR storage format.

  `rocsparse_csrgeam` multiplies the scalar \(\alpha\) with the sparse \(m \times n\) matrix \(A\), defined in CSR storage format, multiplies the scalar \(\beta\) with the sparse \(m \times n\) matrix \(B\), defined in CSR storage format, and adds both resulting matrices to obtain the sparse \(m \times n\) matrix \(C\), defined in CSR storage format, such that

  \[ C := \alpha \cdot A + \beta \cdot B. \]

  It is assumed that `csr_row_ptr_C` has already been filled and that `csr_val_C` and `csr_col_ind_C` are allocated by the user. `csr_row_ptr_C` and allocation size of `csr_col_ind_C` and `csr_val_C` is defined by the number of non-zero elements of the sparse CSR matrix C. Both can be obtained by rocsparse_csrgeam_nnz().

  Example

    This example adds two CSR matrices.

        // Initialize scalar multipliers
        float alpha = 1.0f;
        float beta  = 1.0f;

        // Create matrix descriptors
        rocsparse_mat_descr descr_A;
        rocsparse_mat_descr descr_B;
        rocsparse_mat_descr descr_C;

        rocsparse_create_mat_descr(&descr_A);
        rocsparse_create_mat_descr(&descr_B);
        rocsparse_create_mat_descr(&descr_C);

        // Set pointer mode
        rocsparse_set_pointer_mode(handle, rocsparse_pointer_mode_host);

        // Obtain number of total non-zero entries in C and row pointers of C
        rocsparse_int nnz_C;
        hipMalloc((void**)&csr_row_ptr_C, sizeof(rocsparse_int) * (m + 1));

        rocsparse_csrgeam_nnz(handle,
                              m,
                              n,
                              descr_A,
                              nnz_A,
                              csr_row_ptr_A,
                              csr_col_ind_A,
                              descr_B,
                              nnz_B,
                              csr_row_ptr_B,
                              csr_col_ind_B,
                              descr_C,
                              csr_row_ptr_C,
                              &nnz_C);

        // Compute column indices and values of C
        hipMalloc((void**)&csr_col_ind_C, sizeof(rocsparse_int) * nnz_C);
        hipMalloc((void**)&csr_val_C, sizeof(float) * nnz_C);

        rocsparse_scsrgeam(handle,
                           m,
                           n,
                           &alpha,
                           descr_A,
                           nnz_A,
                           csr_val_A,
                           csr_row_ptr_A,
                           csr_col_ind_A,
                           &beta,
                           descr_B,
                           nnz_B,
                           csr_val_B,
                           csr_row_ptr_B,
                           csr_col_ind_B,
                           descr_C,
                           csr_val_C,
                           csr_row_ptr_C,
                           csr_col_ind_C);

  Note

  Both scalars \(\alpha\) and \(beta\) have to be valid.

  Note

  Currently, only rocsparse_matrix_type_general is supported.

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows of the sparse CSR matrix \(A\), \(B\) and \(C\).

    - n – [in] number of columns of the sparse CSR matrix \(A\), \(B\) and \(C\).

    - alpha – [in] scalar \(\alpha\).

    - descr_A – [in] descriptor of the sparse CSR matrix \(A\). Currenty, only rocsparse_matrix_type_general is supported.

    - nnz_A – [in] number of non-zero entries of the sparse CSR matrix \(A\).

    - csr_val_A – [in] array of `nnz_A` elements of the sparse CSR matrix \(A\).

    - csr_row_ptr_A – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix \(A\).

    - csr_col_ind_A – [in] array of `nnz_A` elements containing the column indices of the sparse CSR matrix \(A\).

    - beta – [in] scalar \(\beta\).

    - descr_B – [in] descriptor of the sparse CSR matrix \(B\). Currenty, only rocsparse_matrix_type_general is supported.

    - nnz_B – [in] number of non-zero entries of the sparse CSR matrix \(B\).

    - csr_val_B – [in] array of `nnz_B` elements of the sparse CSR matrix \(B\).

    - csr_row_ptr_B – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix \(B\).

    - csr_col_ind_B – [in] array of `nnz_B` elements containing the column indices of the sparse CSR matrix \(B\).

    - descr_C – [in] descriptor of the sparse CSR matrix \(C\). Currenty, only rocsparse_matrix_type_general is supported.

    - csr_val_C – [out] array of elements of the sparse CSR matrix \(C\).

    - csr_row_ptr_C – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix \(C\).

    - csr_col_ind_C – [out] array of elements containing the column indices of the sparse CSR matrix \(C\).

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m`, `n`, `nnz_A` or `nnz_B` is invalid.

    - rocsparse_status_invalid_pointer – `alpha`, `descr_A`, `csr_val_A`, `csr_row_ptr_A`, `csr_col_ind_A`, `beta`, `descr_B`, `csr_val_B`, `csr_row_ptr_B`, `csr_col_ind_B`, `descr_C`, `csr_val_C`, `csr_row_ptr_C` or `csr_col_ind_C` is invalid.

    - rocsparse_status_not_implemented – `rocsparse_matrix_type` != rocsparse_matrix_type_general.

### rocsparse_csrgemm_buffer_size()

rocsparse_status rocsparse_scsrgemm_buffer_size(rocsparse_handle handle, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int m, rocsparse_int n, rocsparse_int k, const float *alpha, const rocsparse_mat_descr descr_A, rocsparse_int nnz_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, const rocsparse_mat_descr descr_B, rocsparse_int nnz_B, const rocsparse_int *csr_row_ptr_B, const rocsparse_int *csr_col_ind_B, const float *beta, const rocsparse_mat_descr descr_D, rocsparse_int nnz_D, const rocsparse_int *csr_row_ptr_D, const rocsparse_int *csr_col_ind_D, rocsparse_mat_info info_C, size_t *buffer_size)

rocsparse_status rocsparse_dcsrgemm_buffer_size(rocsparse_handle handle, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int m, rocsparse_int n, rocsparse_int k, const double *alpha, const rocsparse_mat_descr descr_A, rocsparse_int nnz_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, const rocsparse_mat_descr descr_B, rocsparse_int nnz_B, const rocsparse_int *csr_row_ptr_B, const rocsparse_int *csr_col_ind_B, const double *beta, const rocsparse_mat_descr descr_D, rocsparse_int nnz_D, const rocsparse_int *csr_row_ptr_D, const rocsparse_int *csr_col_ind_D, rocsparse_mat_info info_C, size_t *buffer_size)

rocsparse_status rocsparse_ccsrgemm_buffer_size(rocsparse_handle handle, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int m, rocsparse_int n, rocsparse_int k, const rocsparse_float_complex *alpha, const rocsparse_mat_descr descr_A, rocsparse_int nnz_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, const rocsparse_mat_descr descr_B, rocsparse_int nnz_B, const rocsparse_int *csr_row_ptr_B, const rocsparse_int *csr_col_ind_B, const rocsparse_float_complex *beta, const rocsparse_mat_descr descr_D, rocsparse_int nnz_D, const rocsparse_int *csr_row_ptr_D, const rocsparse_int *csr_col_ind_D, rocsparse_mat_info info_C, size_t *buffer_size)

rocsparse_status rocsparse_zcsrgemm_buffer_size(rocsparse_handle handle, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int m, rocsparse_int n, rocsparse_int k, const rocsparse_double_complex *alpha, const rocsparse_mat_descr descr_A, rocsparse_int nnz_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, const rocsparse_mat_descr descr_B, rocsparse_int nnz_B, const rocsparse_int *csr_row_ptr_B, const rocsparse_int *csr_col_ind_B, const rocsparse_double_complex *beta, const rocsparse_mat_descr descr_D, rocsparse_int nnz_D, const rocsparse_int *csr_row_ptr_D, const rocsparse_int *csr_col_ind_D, rocsparse_mat_info info_C, size_t *buffer_size)

  Sparse matrix sparse matrix multiplication using CSR storage format.

  `rocsparse_csrgemm_buffer_size` returns the size of the temporary storage buffer that is required by rocsparse_csrgemm_nnz(), rocsparse_scsrgemm(), rocsparse_dcsrgemm(), rocsparse_ccsrgemm() and rocsparse_zcsrgemm(). The temporary storage buffer must be allocated by the user.

  Note

  Please note, that for matrix products with more than 4096 non-zero entries per row, additional temporary storage buffer is allocated by the algorithm.

  Note

  Please note, that for matrix products with more than 8192 intermediate products per row, additional temporary storage buffer is allocated by the algorithm.

  Note

  Currently, only `trans_A` == `trans_B` == rocsparse_operation_none is supported.

  Note

  Currently, only rocsparse_matrix_type_general is supported.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - trans_A – [in] matrix \(A\) operation type.

    - trans_B – [in] matrix \(B\) operation type.

    - m – [in] number of rows of the sparse CSR matrix \(op(A)\) and \(C\).

    - n – [in] number of columns of the sparse CSR matrix \(op(B)\) and \(C\).

    - k – [in] number of columns of the sparse CSR matrix \(op(A)\) and number of rows of the sparse CSR matrix \(op(B)\).

    - alpha – [in] scalar \(\alpha\).

    - descr_A – [in] descriptor of the sparse CSR matrix \(A\). Currenty, only rocsparse_matrix_type_general is supported.

    - nnz_A – [in] number of non-zero entries of the sparse CSR matrix \(A\).

    - csr_row_ptr_A – [in] array of `m+1` elements ( \(op(A) == A\), `k+1` otherwise) that point to the start of every row of the sparse CSR matrix \(op(A)\).

    - csr_col_ind_A – [in] array of `nnz_A` elements containing the column indices of the sparse CSR matrix \(A\).

    - descr_B – [in] descriptor of the sparse CSR matrix \(B\). Currenty, only rocsparse_matrix_type_general is supported.

    - nnz_B – [in] number of non-zero entries of the sparse CSR matrix \(B\).

    - csr_row_ptr_B – [in] array of `k+1` elements ( \(op(B) == B\), `m+1` otherwise) that point to the start of every row of the sparse CSR matrix \(op(B)\).

    - csr_col_ind_B – [in] array of `nnz_B` elements containing the column indices of the sparse CSR matrix \(B\).

    - beta – [in] scalar \(\beta\).

    - descr_D – [in] descriptor of the sparse CSR matrix \(D\). Currenty, only rocsparse_matrix_type_general is supported.

    - nnz_D – [in] number of non-zero entries of the sparse CSR matrix \(D\).

    - csr_row_ptr_D – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix \(D\).

    - csr_col_ind_D – [in] array of `nnz_D` elements containing the column indices of the sparse CSR matrix \(D\).

    - info_C – [inout] structure that holds meta data for the sparse CSR matrix \(C\).

    - buffer_size – [out] number of bytes of the temporary storage buffer required by rocsparse_csrgemm_nnz(), rocsparse_scsrgemm(), rocsparse_dcsrgemm(), rocsparse_ccsrgemm() and rocsparse_zcsrgemm().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m`, `n`, `k`, `nnz_A`, `nnz_B` or `nnz_D` is invalid.

    - rocsparse_status_invalid_pointer – `alpha` and `beta` are invalid, `descr_A`, `csr_row_ptr_A`, `csr_col_ind_A`, `descr_B`, `csr_row_ptr_B` or `csr_col_ind_B` are invalid if `alpha` is valid, `descr_D`, `csr_row_ptr_D` or `csr_col_ind_D` is invalid if `beta` is valid, `info_C` or `buffer_size` is invalid.

    - rocsparse_status_not_implemented – `trans_A` != rocsparse_operation_none, `trans_B` != rocsparse_operation_none, or `rocsparse_matrix_type` != rocsparse_matrix_type_general.

### rocsparse_csrgemm_nnz()

rocsparse_status rocsparse_csrgemm_nnz(rocsparse_handle handle, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int m, rocsparse_int n, rocsparse_int k, const rocsparse_mat_descr descr_A, rocsparse_int nnz_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, const rocsparse_mat_descr descr_B, rocsparse_int nnz_B, const rocsparse_int *csr_row_ptr_B, const rocsparse_int *csr_col_ind_B, const rocsparse_mat_descr descr_D, rocsparse_int nnz_D, const rocsparse_int *csr_row_ptr_D, const rocsparse_int *csr_col_ind_D, const rocsparse_mat_descr descr_C, rocsparse_int *csr_row_ptr_C, rocsparse_int *nnz_C, const rocsparse_mat_info info_C, void *temp_buffer)

  Sparse matrix sparse matrix multiplication using CSR storage format.

  `rocsparse_csrgemm_nnz` computes the total CSR non-zero elements and the CSR row offsets, that point to the start of every row of the sparse CSR matrix, of the resulting multiplied matrix C. It is assumed that `csr_row_ptr_C` has been allocated with size `m+1`. The required buffer size can be obtained by rocsparse_scsrgemm_buffer_size(), rocsparse_dcsrgemm_buffer_size(), rocsparse_ccsrgemm_buffer_size() and rocsparse_zcsrgemm_buffer_size(), respectively.

  Note

  Please note, that for matrix products with more than 8192 intermediate products per row, additional temporary storage buffer is allocated by the algorithm.

  Note

  This function supports unsorted CSR matrices as input, while output will be sorted. Please note that matrices B and D can only be unsorted up to 8192 intermediate products per row. If this number is exceeded, rocsparse_status_requires_sorted_storage will be returned.

  Note

  This function is blocking with respect to the host.

  Note

  Currently, only `trans_A` == `trans_B` == rocsparse_operation_none is supported.

  Note

  Currently, only rocsparse_matrix_type_general is supported.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - trans_A – [in] matrix \(A\) operation type.

    - trans_B – [in] matrix \(B\) operation type.

    - m – [in] number of rows of the sparse CSR matrix \(op(A)\) and \(C\).

    - n – [in] number of columns of the sparse CSR matrix \(op(B)\) and \(C\).

    - k – [in] number of columns of the sparse CSR matrix \(op(A)\) and number of rows of the sparse CSR matrix \(op(B)\).

    - descr_A – [in] descriptor of the sparse CSR matrix \(A\). Currenty, only rocsparse_matrix_type_general is supported.

    - nnz_A – [in] number of non-zero entries of the sparse CSR matrix \(A\).

    - csr_row_ptr_A – [in] array of `m+1` elements ( \(op(A) == A\), `k+1` otherwise) that point to the start of every row of the sparse CSR matrix \(op(A)\).

    - csr_col_ind_A – [in] array of `nnz_A` elements containing the column indices of the sparse CSR matrix \(A\).

    - descr_B – [in] descriptor of the sparse CSR matrix \(B\). Currenty, only rocsparse_matrix_type_general is supported.

    - nnz_B – [in] number of non-zero entries of the sparse CSR matrix \(B\).

    - csr_row_ptr_B – [in] array of `k+1` elements ( \(op(B) == B\), `m+1` otherwise) that point to the start of every row of the sparse CSR matrix \(op(B)\).

    - csr_col_ind_B – [in] array of `nnz_B` elements containing the column indices of the sparse CSR matrix \(B\).

    - descr_D – [in] descriptor of the sparse CSR matrix \(D\). Currenty, only rocsparse_matrix_type_general is supported.

    - nnz_D – [in] number of non-zero entries of the sparse CSR matrix \(D\).

    - csr_row_ptr_D – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix \(D\).

    - csr_col_ind_D – [in] array of `nnz_D` elements containing the column indices of the sparse CSR matrix \(D\).

    - descr_C – [in] descriptor of the sparse CSR matrix \(C\). Currenty, only rocsparse_matrix_type_general is supported.

    - csr_row_ptr_C – [out] array of `m+1` elements that point to the start of every row of the sparse CSR matrix \(C\).

    - nnz_C – [out] pointer to the number of non-zero entries of the sparse CSR matrix \(C\).

    - info_C – [in] structure that holds meta data for the sparse CSR matrix \(C\).

    - temp_buffer – [in] temporary storage buffer allocated by the user, size is returned by rocsparse_scsrgemm_buffer_size(), rocsparse_dcsrgemm_buffer_size(), rocsparse_ccsrgemm_buffer_size() or rocsparse_zcsrgemm_buffer_size().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m`, `n`, `k`, `nnz_A`, `nnz_B` or `nnz_D` is invalid.

    - rocsparse_status_invalid_pointer – `descr_A`, `csr_row_ptr_A`, `csr_col_ind_A`, `descr_B`, `csr_row_ptr_B`, `csr_col_ind_B`, `descr_D`, `csr_row_ptr_D`, `csr_col_ind_D`, `descr_C`, `csr_row_ptr_C`, `nnz_C`, `info_C` or `temp_buffer` is invalid.

    - rocsparse_status_memory_error – additional buffer for long rows could not be allocated.

    - rocsparse_status_not_implemented – `trans_A` != rocsparse_operation_none, `trans_B` != rocsparse_operation_none, or `rocsparse_matrix_type` != rocsparse_matrix_type_general.

### rocsparse_csrgemm_symbolic()

rocsparse_status rocsparse_csrgemm_symbolic(rocsparse_handle handle, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int m, rocsparse_int n, rocsparse_int k, const rocsparse_mat_descr descr_A, rocsparse_int nnz_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, const rocsparse_mat_descr descr_B, rocsparse_int nnz_B, const rocsparse_int *csr_row_ptr_B, const rocsparse_int *csr_col_ind_B, const rocsparse_mat_descr descr_D, rocsparse_int nnz_D, const rocsparse_int *csr_row_ptr_D, const rocsparse_int *csr_col_ind_D, const rocsparse_mat_descr descr_C, rocsparse_int nnz_C, const rocsparse_int *csr_row_ptr_C, rocsparse_int *csr_col_ind_C, const rocsparse_mat_info info_C, void *temp_buffer)

  Sparse matrix sparse matrix symbolic multiplication using CSR storage format.

  `rocsparse_csrgemm_symbolic` multiplies two sparsity patterns and add an extra one:

  \[ opA \cdot op(B) + D \]
  with \(m \times k\) matrix \(A\), defined in CSR storage format, the sparse \(k \times n\) matrix \(B\), defined in CSR storage format and the sparse \(m \times n\) matrix \(D\). The * final result is stored in the sparse \(m \times n\) matrix \(C\), defined in CSR storage format, such that
  \[ C := op(A) \cdot op(B) + D, \]
  with
  \[\begin{split} op(A) = \left\{ \begin{array}{ll} A, & \text{if trans_A == rocsparse_operation_none} \\ A^T, & \text{if trans_A == rocsparse_operation_transpose} \\ A^H, & \text{if trans_A == rocsparse_operation_conjugate_transpose} \end{array} \right. \end{split}\]
  and
  \[\begin{split} op(B) = \left\{ \begin{array}{ll} B, & \text{if trans_B == rocsparse_operation_none} \\ B^T, & \text{if trans_B == rocsparse_operation_transpose} \\ B^H, & \text{if trans_B == rocsparse_operation_conjugate_transpose} \end{array} \right. \end{split}\]

  It is assumed that `csr_row_ptr_C` has already been filled and that and `csr_col_ind_C` is allocated by the user. `csr_row_ptr_C` and allocation size of `csr_col_ind_C` is defined by the number of non-zero elements of the sparse CSR matrix C. Both can be obtained by rocsparse_csrgemm_nnz(). The required buffer size for the computation can be obtained by rocsparse_scsrgemm_buffer_size(), rocsparse_dcsrgemm_buffer_size(), rocsparse_ccsrgemm_buffer_size() and rocsparse_zcsrgemm_buffer_size(), respectively.

  Example

    This example multiplies symbolically two CSR matrices and adds the result to another CSR matrix.

        // Initialize scalar multipliers
        float alpha = 2.0f;
        float beta  = 1.0f;

        // Create matrix descriptors
        rocsparse_mat_descr descr_A;
        rocsparse_mat_descr descr_B;
        rocsparse_mat_descr descr_C;
        rocsparse_mat_descr descr_D;

        rocsparse_create_mat_descr(&descr_A);
        rocsparse_create_mat_descr(&descr_B);
        rocsparse_create_mat_descr(&descr_C);
        rocsparse_create_mat_descr(&descr_D);

        // Create matrix info structure
        rocsparse_mat_info info_C;
        rocsparse_create_mat_info(&info_C);

        // Set pointer mode
        rocsparse_set_pointer_mode(handle, rocsparse_pointer_mode_host);

        // Query rocsparse for the required buffer size
        size_t buffer_size;

        rocsparse_scsrgemm_buffer_size(handle,
                                       rocsparse_operation_none,
                                       rocsparse_operation_none,
                                       m,
                                       n,
                                       k,
                                       &alpha,
                                       descr_A,
                                       nnz_A,
                                       csr_row_ptr_A,
                                       csr_col_ind_A,
                                       descr_B,
                                       nnz_B,
                                       csr_row_ptr_B,
                                       csr_col_ind_B,
                                       &beta,
                                       descr_D,
                                       nnz_D,
                                       csr_row_ptr_D,
                                       csr_col_ind_D,
                                       info_C,
                                       &buffer_size);

        // Allocate buffer
        void* buffer;
        hipMalloc(&buffer, buffer_size);

        // Obtain number of total non-zero entries in C and row pointers of C
        rocsparse_int nnz_C;
        hipMalloc((void**)&csr_row_ptr_C, sizeof(rocsparse_int) * (m + 1));

        rocsparse_csrgemm_nnz(handle,
                              rocsparse_operation_none,
                              rocsparse_operation_none,
                              m,
                              n,
                              k,
                              descr_A,
                              nnz_A,
                              csr_row_ptr_A,
                              csr_col_ind_A,
                              descr_B,
                              nnz_B,
                              csr_row_ptr_B,
                              csr_col_ind_B,
                              descr_D,
                              nnz_D,
                              csr_row_ptr_D,
                              csr_col_ind_D,
                              descr_C,
                              csr_row_ptr_C,
                              &nnz_C,
                              info_C,
                              buffer);

        // Compute column indices of C
        hipMalloc((void**)&csr_col_ind_C, sizeof(rocsparse_int) * nnz_C);

        rocsparse_csrgemm_symbolic(handle,
                           rocsparse_operation_none,
                           rocsparse_operation_none,
                           m,
                           n,
                           k,
                           descr_A,
                           nnz_A,
                           csr_row_ptr_A,
                           csr_col_ind_A,
                           descr_B,
                           nnz_B,
                           csr_row_ptr_B,
                           csr_col_ind_B,
                           descr_D,
                           nnz_D,
                           csr_row_ptr_D,
                           csr_col_ind_D,
                           descr_C,
                           nnz_C,
                           csr_row_ptr_C,
                           csr_col_ind_C,
                           info_C,
                           buffer);

  Note

  Currently, only `trans_A` == rocsparse_operation_none is supported.

  Note

  Currently, only `trans_B` == rocsparse_operation_none is supported.

  Note

  Currently, only rocsparse_matrix_type_general is supported.

  Note

  Please note, that for matrix products with more than 4096 non-zero entries per row, additional temporary storage buffer is allocated by the algorithm.

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - trans_A – [in] matrix \(A\) operation type.

    - trans_B – [in] matrix \(B\) operation type.

    - m – [in] number of rows of the sparse CSR matrix \(op(A)\) and \(C\).

    - n – [in] number of columns of the sparse CSR matrix \(op(B)\) and \(C\).

    - k – [in] number of columns of the sparse CSR matrix \(op(A)\) and number of rows of the sparse CSR matrix \(op(B)\).

    - descr_A – [in] descriptor of the sparse CSR matrix \(A\). Currenty, only rocsparse_matrix_type_general is supported.

    - nnz_A – [in] number of non-zero entries of the sparse CSR matrix \(A\).

    - csr_row_ptr_A – [in] array of `m+1` elements ( \(op(A) == A\), `k+1` otherwise) that point to the start of every row of the sparse CSR matrix \(op(A)\).

    - csr_col_ind_A – [in] array of `nnz_A` elements containing the column indices of the sparse CSR matrix \(A\).

    - descr_B – [in] descriptor of the sparse CSR matrix \(B\). Currenty, only rocsparse_matrix_type_general is supported.

    - nnz_B – [in] number of non-zero entries of the sparse CSR matrix \(B\).

    - csr_row_ptr_B – [in] array of `k+1` elements ( \(op(B) == B\), `m+1` otherwise) that point to the start of every row of the sparse CSR matrix \(op(B)\).

    - csr_col_ind_B – [in] array of `nnz_B` elements containing the column indices of the sparse CSR matrix \(B\).

    - descr_D – [in] descriptor of the sparse CSR matrix \(D\). Currenty, only rocsparse_matrix_type_general is supported.

    - nnz_D – [in] number of non-zero entries of the sparse CSR matrix \(D\).

    - csr_row_ptr_D – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix \(D\).

    - csr_col_ind_D – [in] array of `nnz_D` elements containing the column indices of the sparse CSR matrix \(D\).

    - descr_C – [in] descriptor of the sparse CSR matrix \(C\). Currenty, only rocsparse_matrix_type_general is supported.

    - nnz_C – [in] number of non-zero entries of the sparse CSR matrix \(C\).

    - csr_row_ptr_C – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix \(C\).

    - csr_col_ind_C – [out] array of `nnz_C` elements containing the column indices of the sparse CSR matrix \(C\).

    - info_C – [in] structure that holds meta data for the sparse CSR matrix \(C\).

    - temp_buffer – [in] temporary storage buffer allocated by the user, size is returned by rocsparse_scsrgemm_buffer_size(), rocsparse_dcsrgemm_buffer_size(), rocsparse_ccsrgemm_buffer_size() or rocsparse_zcsrgemm_buffer_size().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m`, `n`, `k`, `nnz_A`, `nnz_B` or `nnz_D` is invalid.

    - rocsparse_status_invalid_pointer – `descr_A`, `csr_row_ptr_A`, `csr_col_ind_A`, `descr_B`, `csr_row_ptr_B` or `csr_col_ind_B`, `descr_D`, `csr_row_ptr_D`, `csr_col_ind_D` `csr_row_ptr_C`, `csr_col_ind_C`, `info_C` or `temp_buffer` is invalid.

    - rocsparse_status_memory_error – additional buffer for long rows could not be allocated.

    - rocsparse_status_not_implemented – `trans_A` != rocsparse_operation_none, `trans_B` != rocsparse_operation_none, or `rocsparse_matrix_type` != rocsparse_matrix_type_general.

### rocsparse_csrgemm()

rocsparse_status rocsparse_scsrgemm(rocsparse_handle handle, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int m, rocsparse_int n, rocsparse_int k, const float *alpha, const rocsparse_mat_descr descr_A, rocsparse_int nnz_A, const float *csr_val_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, const rocsparse_mat_descr descr_B, rocsparse_int nnz_B, const float *csr_val_B, const rocsparse_int *csr_row_ptr_B, const rocsparse_int *csr_col_ind_B, const float *beta, const rocsparse_mat_descr descr_D, rocsparse_int nnz_D, const float *csr_val_D, const rocsparse_int *csr_row_ptr_D, const rocsparse_int *csr_col_ind_D, const rocsparse_mat_descr descr_C, float *csr_val_C, const rocsparse_int *csr_row_ptr_C, rocsparse_int *csr_col_ind_C, const rocsparse_mat_info info_C, void *temp_buffer)

rocsparse_status rocsparse_dcsrgemm(rocsparse_handle handle, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int m, rocsparse_int n, rocsparse_int k, const double *alpha, const rocsparse_mat_descr descr_A, rocsparse_int nnz_A, const double *csr_val_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, const rocsparse_mat_descr descr_B, rocsparse_int nnz_B, const double *csr_val_B, const rocsparse_int *csr_row_ptr_B, const rocsparse_int *csr_col_ind_B, const double *beta, const rocsparse_mat_descr descr_D, rocsparse_int nnz_D, const double *csr_val_D, const rocsparse_int *csr_row_ptr_D, const rocsparse_int *csr_col_ind_D, const rocsparse_mat_descr descr_C, double *csr_val_C, const rocsparse_int *csr_row_ptr_C, rocsparse_int *csr_col_ind_C, const rocsparse_mat_info info_C, void *temp_buffer)

rocsparse_status rocsparse_ccsrgemm(rocsparse_handle handle, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int m, rocsparse_int n, rocsparse_int k, const rocsparse_float_complex *alpha, const rocsparse_mat_descr descr_A, rocsparse_int nnz_A, const rocsparse_float_complex *csr_val_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, const rocsparse_mat_descr descr_B, rocsparse_int nnz_B, const rocsparse_float_complex *csr_val_B, const rocsparse_int *csr_row_ptr_B, const rocsparse_int *csr_col_ind_B, const rocsparse_float_complex *beta, const rocsparse_mat_descr descr_D, rocsparse_int nnz_D, const rocsparse_float_complex *csr_val_D, const rocsparse_int *csr_row_ptr_D, const rocsparse_int *csr_col_ind_D, const rocsparse_mat_descr descr_C, rocsparse_float_complex *csr_val_C, const rocsparse_int *csr_row_ptr_C, rocsparse_int *csr_col_ind_C, const rocsparse_mat_info info_C, void *temp_buffer)

rocsparse_status rocsparse_zcsrgemm(rocsparse_handle handle, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int m, rocsparse_int n, rocsparse_int k, const rocsparse_double_complex *alpha, const rocsparse_mat_descr descr_A, rocsparse_int nnz_A, const rocsparse_double_complex *csr_val_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, const rocsparse_mat_descr descr_B, rocsparse_int nnz_B, const rocsparse_double_complex *csr_val_B, const rocsparse_int *csr_row_ptr_B, const rocsparse_int *csr_col_ind_B, const rocsparse_double_complex *beta, const rocsparse_mat_descr descr_D, rocsparse_int nnz_D, const rocsparse_double_complex *csr_val_D, const rocsparse_int *csr_row_ptr_D, const rocsparse_int *csr_col_ind_D, const rocsparse_mat_descr descr_C, rocsparse_double_complex *csr_val_C, const rocsparse_int *csr_row_ptr_C, rocsparse_int *csr_col_ind_C, const rocsparse_mat_info info_C, void *temp_buffer)

  Sparse matrix sparse matrix multiplication using CSR storage format.

  `rocsparse_csrgemm` multiplies the scalar \(\alpha\) with the sparse \(m \times k\) matrix \(A\), defined in CSR storage format, and the sparse \(k \times n\) matrix \(B\), defined in CSR storage format, and adds the result to the sparse \(m \times n\) matrix \(D\) that is multiplied by \(\beta\). The final result is stored in the sparse \(m \times n\) matrix \(C\), defined in CSR storage format, such that

  \[ C := \alpha \cdot op(A) \cdot op(B) + \beta \cdot D, \]
  with
  \[\begin{split} op(A) = \left\{ \begin{array}{ll} A, & \text{if trans_A == rocsparse_operation_none} \\ A^T, & \text{if trans_A == rocsparse_operation_transpose} \\ A^H, & \text{if trans_A == rocsparse_operation_conjugate_transpose} \end{array} \right. \end{split}\]
  and
  \[\begin{split} op(B) = \left\{ \begin{array}{ll} B, & \text{if trans_B == rocsparse_operation_none} \\ B^T, & \text{if trans_B == rocsparse_operation_transpose} \\ B^H, & \text{if trans_B == rocsparse_operation_conjugate_transpose} \end{array} \right. \end{split}\]

  It is assumed that `csr_row_ptr_C` has already been filled and that `csr_val_C` and `csr_col_ind_C` are allocated by the user. `csr_row_ptr_C` and allocation size of `csr_col_ind_C` and `csr_val_C` is defined by the number of non-zero elements of the sparse CSR matrix C. Both can be obtained by rocsparse_csrgemm_nnz(). The required buffer size for the computation can be obtained by rocsparse_scsrgemm_buffer_size(), rocsparse_dcsrgemm_buffer_size(), rocsparse_ccsrgemm_buffer_size() and rocsparse_zcsrgemm_buffer_size(), respectively.

  Example

    This example multiplies two CSR matrices with a scalar alpha and adds the result to another CSR matrix.

        // Initialize scalar multipliers
        float alpha = 2.0f;
        float beta  = 1.0f;

        // Create matrix descriptors
        rocsparse_mat_descr descr_A;
        rocsparse_mat_descr descr_B;
        rocsparse_mat_descr descr_C;
        rocsparse_mat_descr descr_D;

        rocsparse_create_mat_descr(&descr_A);
        rocsparse_create_mat_descr(&descr_B);
        rocsparse_create_mat_descr(&descr_C);
        rocsparse_create_mat_descr(&descr_D);

        // Create matrix info structure
        rocsparse_mat_info info_C;
        rocsparse_create_mat_info(&info_C);

        // Set pointer mode
        rocsparse_set_pointer_mode(handle, rocsparse_pointer_mode_host);

        // Query rocsparse for the required buffer size
        size_t buffer_size;

        rocsparse_scsrgemm_buffer_size(handle,
                                       rocsparse_operation_none,
                                       rocsparse_operation_none,
                                       m,
                                       n,
                                       k,
                                       &alpha,
                                       descr_A,
                                       nnz_A,
                                       csr_row_ptr_A,
                                       csr_col_ind_A,
                                       descr_B,
                                       nnz_B,
                                       csr_row_ptr_B,
                                       csr_col_ind_B,
                                       &beta,
                                       descr_D,
                                       nnz_D,
                                       csr_row_ptr_D,
                                       csr_col_ind_D,
                                       info_C,
                                       &buffer_size);

        // Allocate buffer
        void* buffer;
        hipMalloc(&buffer, buffer_size);

        // Obtain number of total non-zero entries in C and row pointers of C
        rocsparse_int nnz_C;
        hipMalloc((void**)&csr_row_ptr_C, sizeof(rocsparse_int) * (m + 1));

        rocsparse_csrgemm_nnz(handle,
                              rocsparse_operation_none,
                              rocsparse_operation_none,
                              m,
                              n,
                              k,
                              descr_A,
                              nnz_A,
                              csr_row_ptr_A,
                              csr_col_ind_A,
                              descr_B,
                              nnz_B,
                              csr_row_ptr_B,
                              csr_col_ind_B,
                              descr_D,
                              nnz_D,
                              csr_row_ptr_D,
                              csr_col_ind_D,
                              descr_C,
                              csr_row_ptr_C,
                              &nnz_C,
                              info_C,
                              buffer);

        // Compute column indices and values of C
        hipMalloc((void**)&csr_col_ind_C, sizeof(rocsparse_int) * nnz_C);
        hipMalloc((void**)&csr_val_C, sizeof(float) * nnz_C);

        rocsparse_scsrgemm(handle,
                           rocsparse_operation_none,
                           rocsparse_operation_none,
                           m,
                           n,
                           k,
                           &alpha,
                           descr_A,
                           nnz_A,
                           csr_val_A,
                           csr_row_ptr_A,
                           csr_col_ind_A,
                           descr_B,
                           nnz_B,
                           csr_val_B,
                           csr_row_ptr_B,
                           csr_col_ind_B,
                           &beta,
                           descr_D,
                           nnz_D,
                           csr_val_D,
                           csr_row_ptr_D,
                           csr_col_ind_D,
                           descr_C,
                           csr_val_C,
                           csr_row_ptr_C,
                           csr_col_ind_C,
                           info_C,
                           buffer);

  Note

  If \(\alpha == 0\), then \(C = \beta \cdot D\) will be computed.

  Note

  If \(\beta == 0\), then \(C = \alpha \cdot op(A) \cdot op(B)\) will be computed.

  Note

  \(\alpha == beta == 0\) is invalid.

  Note

  Currently, only `trans_A` == rocsparse_operation_none is supported.

  Note

  Currently, only `trans_B` == rocsparse_operation_none is supported.

  Note

  Currently, only rocsparse_matrix_type_general is supported.

  Note

  Please note, that for matrix products with more than 4096 non-zero entries per row, additional temporary storage buffer is allocated by the algorithm.

  Note

  This function supports unsorted CSR matrices as input, while output will be sorted. Please note that matrices B and D can only be unsorted up to 4096 non-zero entries per row. If this number is exceeded, rocsparse_status_requires_sorted_storage will be returned.

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - trans_A – [in] matrix \(A\) operation type.

    - trans_B – [in] matrix \(B\) operation type.

    - m – [in] number of rows of the sparse CSR matrix \(op(A)\) and \(C\).

    - n – [in] number of columns of the sparse CSR matrix \(op(B)\) and \(C\).

    - k – [in] number of columns of the sparse CSR matrix \(op(A)\) and number of rows of the sparse CSR matrix \(op(B)\).

    - alpha – [in] scalar \(\alpha\).

    - descr_A – [in] descriptor of the sparse CSR matrix \(A\). Currenty, only rocsparse_matrix_type_general is supported.

    - nnz_A – [in] number of non-zero entries of the sparse CSR matrix \(A\).

    - csr_val_A – [in] array of `nnz_A` elements of the sparse CSR matrix \(A\).

    - csr_row_ptr_A – [in] array of `m+1` elements ( \(op(A) == A\), `k+1` otherwise) that point to the start of every row of the sparse CSR matrix \(op(A)\).

    - csr_col_ind_A – [in] array of `nnz_A` elements containing the column indices of the sparse CSR matrix \(A\).

    - descr_B – [in] descriptor of the sparse CSR matrix \(B\). Currenty, only rocsparse_matrix_type_general is supported.

    - nnz_B – [in] number of non-zero entries of the sparse CSR matrix \(B\).

    - csr_val_B – [in] array of `nnz_B` elements of the sparse CSR matrix \(B\).

    - csr_row_ptr_B – [in] array of `k+1` elements ( \(op(B) == B\), `m+1` otherwise) that point to the start of every row of the sparse CSR matrix \(op(B)\).

    - csr_col_ind_B – [in] array of `nnz_B` elements containing the column indices of the sparse CSR matrix \(B\).

    - beta – [in] scalar \(\beta\).

    - descr_D – [in] descriptor of the sparse CSR matrix \(D\). Currenty, only rocsparse_matrix_type_general is supported.

    - nnz_D – [in] number of non-zero entries of the sparse CSR matrix \(D\).

    - csr_val_D – [in] array of `nnz_D` elements of the sparse CSR matrix \(D\).

    - csr_row_ptr_D – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix \(D\).

    - csr_col_ind_D – [in] array of `nnz_D` elements containing the column indices of the sparse CSR matrix \(D\).

    - descr_C – [in] descriptor of the sparse CSR matrix \(C\). Currenty, only rocsparse_matrix_type_general is supported.

    - csr_val_C – [out] array of `nnz_C` elements of the sparse CSR matrix \(C\).

    - csr_row_ptr_C – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix \(C\).

    - csr_col_ind_C – [out] array of `nnz_C` elements containing the column indices of the sparse CSR matrix \(C\).

    - info_C – [in] structure that holds meta data for the sparse CSR matrix \(C\).

    - temp_buffer – [in] temporary storage buffer allocated by the user, size is returned by rocsparse_scsrgemm_buffer_size(), rocsparse_dcsrgemm_buffer_size(), rocsparse_ccsrgemm_buffer_size() or rocsparse_zcsrgemm_buffer_size().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m`, `n`, `k`, `nnz_A`, `nnz_B` or `nnz_D` is invalid.

    - rocsparse_status_invalid_pointer – `alpha` and `beta` are invalid, `descr_A`, `csr_val_A`, `csr_row_ptr_A`, `csr_col_ind_A`, `descr_B`, `csr_val_B`, `csr_row_ptr_B` or `csr_col_ind_B` are invalid if `alpha` is valid, `descr_D`, `csr_val_D`, `csr_row_ptr_D` or `csr_col_ind_D` is invalid if `beta` is valid, `csr_val_C`, `csr_row_ptr_C`, `csr_col_ind_C`, `info_C` or `temp_buffer` is invalid.

    - rocsparse_status_memory_error – additional buffer for long rows could not be allocated.

    - rocsparse_status_not_implemented – `trans_A` != rocsparse_operation_none, `trans_B` != rocsparse_operation_none, or `rocsparse_matrix_type` != rocsparse_matrix_type_general.

### rocsparse_csrgemm_numeric()

rocsparse_status rocsparse_scsrgemm_numeric(rocsparse_handle handle, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int m, rocsparse_int n, rocsparse_int k, const float *alpha, const rocsparse_mat_descr descr_A, rocsparse_int nnz_A, const float *csr_val_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, const rocsparse_mat_descr descr_B, rocsparse_int nnz_B, const float *csr_val_B, const rocsparse_int *csr_row_ptr_B, const rocsparse_int *csr_col_ind_B, const float *beta, const rocsparse_mat_descr descr_D, rocsparse_int nnz_D, const float *csr_val_D, const rocsparse_int *csr_row_ptr_D, const rocsparse_int *csr_col_ind_D, const rocsparse_mat_descr descr_C, rocsparse_int nnz_C, float *csr_val_C, const rocsparse_int *csr_row_ptr_C, const rocsparse_int *csr_col_ind_C, const rocsparse_mat_info info_C, void *temp_buffer)

rocsparse_status rocsparse_dcsrgemm_numeric(rocsparse_handle handle, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int m, rocsparse_int n, rocsparse_int k, const double *alpha, const rocsparse_mat_descr descr_A, rocsparse_int nnz_A, const double *csr_val_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, const rocsparse_mat_descr descr_B, rocsparse_int nnz_B, const double *csr_val_B, const rocsparse_int *csr_row_ptr_B, const rocsparse_int *csr_col_ind_B, const double *beta, const rocsparse_mat_descr descr_D, rocsparse_int nnz_D, const double *csr_val_D, const rocsparse_int *csr_row_ptr_D, const rocsparse_int *csr_col_ind_D, const rocsparse_mat_descr descr_C, rocsparse_int nnz_C, double *csr_val_C, const rocsparse_int *csr_row_ptr_C, const rocsparse_int *csr_col_ind_C, const rocsparse_mat_info info_C, void *temp_buffer)

rocsparse_status rocsparse_ccsrgemm_numeric(rocsparse_handle handle, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int m, rocsparse_int n, rocsparse_int k, const rocsparse_float_complex *alpha, const rocsparse_mat_descr descr_A, rocsparse_int nnz_A, const rocsparse_float_complex *csr_val_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, const rocsparse_mat_descr descr_B, rocsparse_int nnz_B, const rocsparse_float_complex *csr_val_B, const rocsparse_int *csr_row_ptr_B, const rocsparse_int *csr_col_ind_B, const rocsparse_float_complex *beta, const rocsparse_mat_descr descr_D, rocsparse_int nnz_D, const rocsparse_float_complex *csr_val_D, const rocsparse_int *csr_row_ptr_D, const rocsparse_int *csr_col_ind_D, const rocsparse_mat_descr descr_C, rocsparse_int nnz_C, rocsparse_float_complex *csr_val_C, const rocsparse_int *csr_row_ptr_C, const rocsparse_int *csr_col_ind_C, const rocsparse_mat_info info_C, void *temp_buffer)

rocsparse_status rocsparse_zcsrgemm_numeric(rocsparse_handle handle, rocsparse_operation trans_A, rocsparse_operation trans_B, rocsparse_int m, rocsparse_int n, rocsparse_int k, const rocsparse_double_complex *alpha, const rocsparse_mat_descr descr_A, rocsparse_int nnz_A, const rocsparse_double_complex *csr_val_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, const rocsparse_mat_descr descr_B, rocsparse_int nnz_B, const rocsparse_double_complex *csr_val_B, const rocsparse_int *csr_row_ptr_B, const rocsparse_int *csr_col_ind_B, const rocsparse_double_complex *beta, const rocsparse_mat_descr descr_D, rocsparse_int nnz_D, const rocsparse_double_complex *csr_val_D, const rocsparse_int *csr_row_ptr_D, const rocsparse_int *csr_col_ind_D, const rocsparse_mat_descr descr_C, rocsparse_int nnz_C, rocsparse_double_complex *csr_val_C, const rocsparse_int *csr_row_ptr_C, const rocsparse_int *csr_col_ind_C, const rocsparse_mat_info info_C, void *temp_buffer)

  Sparse matrix sparse matrix numeric multiplication using CSR storage format.

  `rocsparse_csrgemm_numeric` multiplies the scalar \(\alpha\) with the sparse \(m \times k\) matrix \(A\), defined in CSR storage format, and the sparse \(k \times n\) matrix \(B\), defined in CSR storage format, and adds the result to the sparse \(m \times n\) matrix \(D\) that is multiplied by \(\beta\). The final result is stored in the sparse \(m \times n\) matrix \(C\), predefined in CSR storage format, such that

  \[ C := \alpha \cdot op(A) \cdot op(B) + \beta \cdot D, \]
  with
  \[\begin{split} op(A) = \left\{ \begin{array}{ll} A, & \text{if trans_A == rocsparse_operation_none} \\ A^T, & \text{if trans_A == rocsparse_operation_transpose} \\ A^H, & \text{if trans_A == rocsparse_operation_conjugate_transpose} \end{array} \right. \end{split}\]
  and
  \[\begin{split} op(B) = \left\{ \begin{array}{ll} B, & \text{if trans_B == rocsparse_operation_none} \\ B^T, & \text{if trans_B == rocsparse_operation_transpose} \\ B^H, & \text{if trans_B == rocsparse_operation_conjugate_transpose} \end{array} \right. \end{split}\]

  The symbolic part of the csr matrix C can be obtained by rocsparse_csrgemm_symbolic(). It is assumed that `csr_row_ptr_C` and `csr_col_ind_C` have already been filled and that `csr_val_C` is allocated by the user. `csr_row_ptr_C` and allocation size of `csr_col_ind_C` and `csr_val_C` is defined by the number of non-zero elements of the sparse CSR matrix C. Both can be obtained by rocsparse_csrgemm_nnz(). The required buffer size for the computation can be obtained by rocsparse_scsrgemm_buffer_size(), rocsparse_dcsrgemm_buffer_size(), rocsparse_ccsrgemm_buffer_size() and rocsparse_zcsrgemm_buffer_size(), respectively.

  Example

    This example multiplies two CSR matrices with a scalar alpha and adds the result to another CSR matrix.

        // Initialize scalar multipliers
        float alpha = 2.0f;
        float beta  = 1.0f;

        // Create matrix descriptors
        rocsparse_mat_descr descr_A;
        rocsparse_mat_descr descr_B;
        rocsparse_mat_descr descr_C;
        rocsparse_mat_descr descr_D;

        rocsparse_create_mat_descr(&descr_A);
        rocsparse_create_mat_descr(&descr_B);
        rocsparse_create_mat_descr(&descr_C);
        rocsparse_create_mat_descr(&descr_D);

        // Create matrix info structure
        rocsparse_mat_info info_C;
        rocsparse_create_mat_info(&info_C);

        // Set pointer mode
        rocsparse_set_pointer_mode(handle, rocsparse_pointer_mode_host);

        // Query rocsparse for the required buffer size
        size_t buffer_size;

        rocsparse_scsrgemm_buffer_size(handle,
                                       rocsparse_operation_none,
                                       rocsparse_operation_none,
                                       m,
                                       n,
                                       k,
                                       &alpha,
                                       descr_A,
                                       nnz_A,
                                       csr_row_ptr_A,
                                       csr_col_ind_A,
                                       descr_B,
                                       nnz_B,
                                       csr_row_ptr_B,
                                       csr_col_ind_B,
                                       &beta,
                                       descr_D,
                                       nnz_D,
                                       csr_row_ptr_D,
                                       csr_col_ind_D,
                                       info_C,
                                       &buffer_size);

        // Allocate buffer
        void* buffer;
        hipMalloc(&buffer, buffer_size);

        // Obtain number of total non-zero entries in C and row pointers of C
        rocsparse_int nnz_C;
        hipMalloc((void**)&csr_row_ptr_C, sizeof(rocsparse_int) * (m + 1));

        rocsparse_csrgemm_nnz(handle,
                              rocsparse_operation_none,
                              rocsparse_operation_none,
                              m,
                              n,
                              k,
                              descr_A,
                              nnz_A,
                              csr_row_ptr_A,
                              csr_col_ind_A,
                              descr_B,
                              nnz_B,
                              csr_row_ptr_B,
                              csr_col_ind_B,
                              descr_D,
                              nnz_D,
                              csr_row_ptr_D,
                              csr_col_ind_D,
                              descr_C,
                              csr_row_ptr_C,
                              &nnz_C,
                              info_C,
                              buffer);

        // Compute column indices and values of C
        hipMalloc((void**)&csr_col_ind_C, sizeof(rocsparse_int) * nnz_C);
        rocsparse_csrgemm_symbolic(handle,
                           rocsparse_operation_none,
                           rocsparse_operation_none,
                           m,
                           n,
                           k,
                           descr_A,
                           nnz_A,
                           csr_row_ptr_A,
                           csr_col_ind_A,
                           descr_B,
                           nnz_B,
                           csr_row_ptr_B,
                           csr_col_ind_B,
                           descr_D,
                           nnz_D,
                           csr_row_ptr_D,
                           csr_col_ind_D,
                           descr_C,
                           nnz_C,
                           csr_row_ptr_C,
                           csr_col_ind_C,
                           info_C,
                           buffer);
        hipMalloc((void**)&csr_val_C, sizeof(float) * nnz_C);

        rocsparse_scsrgemm_numeric(handle,
                           rocsparse_operation_none,
                           rocsparse_operation_none,
                           m,
                           n,
                           k,
                           &alpha,
                           descr_A,
                           nnz_A,
                           csr_val_A,
                           csr_row_ptr_A,
                           csr_col_ind_A,
                           descr_B,
                           nnz_B,
                           csr_val_B,
                           csr_row_ptr_B,
                           csr_col_ind_B,
                           &beta,
                           descr_D,
                           nnz_D,
                           csr_val_D,
                           csr_row_ptr_D,
                           csr_col_ind_D,
                           descr_C,
                           nnz_C,
                           csr_val_C,
                           csr_row_ptr_C,
                           csr_col_ind_C,
                           info_C,
                           buffer);

  Note

  If \(\alpha == 0\), then \(C = \beta \cdot D\) will be computed.

  Note

  If \(\beta == 0\), then \(C = \alpha \cdot op(A) \cdot op(B)\) will be computed.

  Note

  \(\alpha == beta == 0\) is invalid.

  Note

  Currently, only `trans_A` == rocsparse_operation_none is supported.

  Note

  Currently, only `trans_B` == rocsparse_operation_none is supported.

  Note

  Currently, only rocsparse_matrix_type_general is supported.

  Note

  Please note, that for matrix products with more than 4096 non-zero entries per row, additional temporary storage buffer is allocated by the algorithm.

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - trans_A – [in] matrix \(A\) operation type.

    - trans_B – [in] matrix \(B\) operation type.

    - m – [in] number of rows of the sparse CSR matrix \(op(A)\) and \(C\).

    - n – [in] number of columns of the sparse CSR matrix \(op(B)\) and \(C\).

    - k – [in] number of columns of the sparse CSR matrix \(op(A)\) and number of rows of the sparse CSR matrix \(op(B)\).

    - alpha – [in] scalar \(\alpha\).

    - descr_A – [in] descriptor of the sparse CSR matrix \(A\). Currenty, only rocsparse_matrix_type_general is supported.

    - nnz_A – [in] number of non-zero entries of the sparse CSR matrix \(A\).

    - csr_val_A – [in] array of `nnz_A` elements of the sparse CSR matrix \(A\).

    - csr_row_ptr_A – [in] array of `m+1` elements ( \(op(A) == A\), `k+1` otherwise) that point to the start of every row of the sparse CSR matrix \(op(A)\).

    - csr_col_ind_A – [in] array of `nnz_A` elements containing the column indices of the sparse CSR matrix \(A\).

    - descr_B – [in] descriptor of the sparse CSR matrix \(B\). Currenty, only rocsparse_matrix_type_general is supported.

    - nnz_B – [in] number of non-zero entries of the sparse CSR matrix \(B\).

    - csr_val_B – [in] array of `nnz_B` elements of the sparse CSR matrix \(B\).

    - csr_row_ptr_B – [in] array of `k+1` elements ( \(op(B) == B\), `m+1` otherwise) that point to the start of every row of the sparse CSR matrix \(op(B)\).

    - csr_col_ind_B – [in] array of `nnz_B` elements containing the column indices of the sparse CSR matrix \(B\).

    - beta – [in] scalar \(\beta\).

    - descr_D – [in] descriptor of the sparse CSR matrix \(D\). Currenty, only rocsparse_matrix_type_general is supported.

    - nnz_D – [in] number of non-zero entries of the sparse CSR matrix \(D\).

    - csr_val_D – [in] array of `nnz_D` elements of the sparse CSR matrix \(D\).

    - csr_row_ptr_D – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix \(D\).

    - csr_col_ind_D – [in] array of `nnz_D` elements containing the column indices of the sparse CSR matrix \(D\).

    - descr_C – [in] descriptor of the sparse CSR matrix \(C\). Currenty, only rocsparse_matrix_type_general is supported.

    - nnz_C – [in] number of non-zero entries of the sparse CSR matrix \(C\).

    - csr_val_C – [out] array of `nnz_C` elements of the sparse CSR matrix \(C\).

    - csr_row_ptr_C – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix \(C\).

    - csr_col_ind_C – [in] array of `nnz_C` elements containing the column indices of the sparse CSR matrix \(C\).

    - info_C – [in] structure that holds meta data for the sparse CSR matrix \(C\).

    - temp_buffer – [in] temporary storage buffer allocated by the user, size is returned by rocsparse_scsrgemm_buffer_size(), rocsparse_dcsrgemm_buffer_size(), rocsparse_ccsrgemm_buffer_size() or rocsparse_zcsrgemm_buffer_size().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m`, `n`, `k`, `nnz_A`, `nnz_B` or `nnz_D` is invalid.

    - rocsparse_status_invalid_pointer – `alpha` and `beta` are invalid, `descr_A`, `csr_val_A`, `csr_row_ptr_A`, `csr_col_ind_A`, `descr_B`, `csr_val_B`, `csr_row_ptr_B` or `csr_col_ind_B` are invalid if `alpha` is valid, `descr_D`, `csr_val_D`, `csr_row_ptr_D` or `csr_col_ind_D` is invalid if `beta` is valid, `csr_val_C`, `csr_row_ptr_C`, `csr_col_ind_C`, `info_C` or `temp_buffer` is invalid.

    - rocsparse_status_memory_error – additional buffer for long rows could not be allocated.

    - rocsparse_status_not_implemented – `trans_A` != rocsparse_operation_none, `trans_B` != rocsparse_operation_none, or `rocsparse_matrix_type` != rocsparse_matrix_type_general.

## Preconditioner Functions

This module holds all sparse preconditioners.

The sparse preconditioners describe manipulations on a matrix in sparse format to obtain a sparse preconditioner matrix.

### rocsparse_bsric0_zero_pivot()

rocsparse_status rocsparse_bsric0_zero_pivot(rocsparse_handle handle, rocsparse_mat_info info, rocsparse_int *position)

  Incomplete Cholesky factorization with 0 fill-ins and no pivoting using BSR storage format.

  `rocsparse_bsric0_zero_pivot` returns rocsparse_status_zero_pivot, if either a structural or numerical zero has been found during rocsparse_sbsric0(), rocsparse_dbsric0(), rocsparse_cbsric0() or rocsparse_zbsric0() computation. The first zero pivot \(j\) at \(A_{j,j}\) is stored in `position`, using same index base as the BSR matrix.

  `position` can be in host or device memory. If no zero pivot has been found, `position` is set to -1 and rocsparse_status_success is returned instead.

  Note

  If a zero pivot is found, `position=j` means that either the diagonal block `A(j,j)` is missing (structural zero) or the diagonal block `A(j,j)` is not positive definite (numerical zero).

  Note

  `rocsparse_bsric0_zero_pivot` is a blocking function. It might influence performance negatively.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - info – [in] structure that holds the information collected during the analysis step.

    - position – [inout] pointer to zero pivot \(j\), can be in host or device memory.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_pointer – `info` or `position` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

    - rocsparse_status_zero_pivot – zero pivot has been found.

### rocsparse_bsric0_buffer_size()

rocsparse_status rocsparse_sbsric0_buffer_size(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nnzb, const rocsparse_mat_descr descr, const float *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, size_t *buffer_size)

rocsparse_status rocsparse_dbsric0_buffer_size(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nnzb, const rocsparse_mat_descr descr, const double *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, size_t *buffer_size)

rocsparse_status rocsparse_cbsric0_buffer_size(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nnzb, const rocsparse_mat_descr descr, const rocsparse_float_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, size_t *buffer_size)

rocsparse_status rocsparse_zbsric0_buffer_size(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nnzb, const rocsparse_mat_descr descr, const rocsparse_double_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, size_t *buffer_size)

  Incomplete Cholesky factorization with 0 fill-ins and no pivoting using BSR storage format.

  `rocsparse_bsric0_buffer_size` returns the size of the temporary storage buffer that is required by rocsparse_sbsric0_analysis(), rocsparse_dbsric0_analysis(), rocsparse_cbsric0_analysis(), rocsparse_zbsric0_analysis(), rocsparse_sbsric0(), rocsparse_dbsric0(), rocsparse_sbsric0() and rocsparse_dbsric0(). The temporary storage buffer must be allocated by the user. The size of the temporary storage buffer is identical to the size returned by rocsparse_sbsrsv_buffer_size(), rocsparse_dbsrsv_buffer_size(), rocsparse_cbsrsv_buffer_size(), rocsparse_zbsrsv_buffer_size(), rocsparse_sbsrilu0_buffer_size(), rocsparse_dbsrilu0_buffer_size(), rocsparse_cbsrilu0_buffer_size() and rocsparse_zbsrilu0_buffer_size() if the matrix sparsity pattern is identical. The user allocated buffer can thus be shared between subsequent calls to those functions.

  Note

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

  Note

  This routine supports execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - dir – [in] direction that specifies whether to count nonzero elements by rocsparse_direction_row or by rocsparse_direction_row.

    - mb – [in] number of block rows in the sparse BSR matrix.

    - nnzb – [in] number of non-zero block entries of the sparse BSR matrix.

    - descr – [in] descriptor of the sparse BSR matrix.

    - bsr_val – [in] array of length `nnzb*block_dim*block_dim` containing the values of the sparse BSR matrix.

    - bsr_row_ptr – [in] array of `mb+1` elements that point to the start of every block row of the sparse BSR matrix.

    - bsr_col_ind – [in] array of `nnzb` elements containing the block column indices of the sparse BSR matrix.

    - block_dim – [in] the block dimension of the BSR matrix. Between 1 and m where `m=mb*block_dim`.

    - info – [out] structure that holds the information collected during the analysis step.

    - buffer_size – [out] number of bytes of the temporary storage buffer required by rocsparse_sbsric0_analysis(), rocsparse_dbsric0_analysis(), rocsparse_cbsric0_analysis(), rocsparse_zbsric0_analysis(), rocsparse_sbsric0(), rocsparse_dbsric0(), rocsparse_cbsric0() and rocsparse_zbsric0().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `mb`, `nnzb`, or `block_dim` is invalid.

    - rocsparse_status_invalid_pointer – `descr`, `bsr_val`, `bsr_row_ptr`, `bsr_col_ind`, `info` or `buffer_size` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

    - rocsparse_status_not_implemented – rocsparse_matrix_type != rocsparse_matrix_type_general.

### rocsparse_bsric0_analysis()

rocsparse_status rocsparse_sbsric0_analysis(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nnzb, const rocsparse_mat_descr descr, const float *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, rocsparse_analysis_policy analysis, rocsparse_solve_policy solve, void *temp_buffer)

rocsparse_status rocsparse_dbsric0_analysis(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nnzb, const rocsparse_mat_descr descr, const double *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, rocsparse_analysis_policy analysis, rocsparse_solve_policy solve, void *temp_buffer)

rocsparse_status rocsparse_cbsric0_analysis(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nnzb, const rocsparse_mat_descr descr, const rocsparse_float_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, rocsparse_analysis_policy analysis, rocsparse_solve_policy solve, void *temp_buffer)

rocsparse_status rocsparse_zbsric0_analysis(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nnzb, const rocsparse_mat_descr descr, const rocsparse_double_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, rocsparse_analysis_policy analysis, rocsparse_solve_policy solve, void *temp_buffer)

  Incomplete Cholesky factorization with 0 fill-ins and no pivoting using BSR storage format.

  `rocsparse_bsric0_analysis` performs the analysis step for rocsparse_sbsric0() rocsparse_dbsric0(), rocsparse_cbsric0(), and rocsparse_zbsric0(). It is expected that this function will be executed only once for a given matrix and particular operation type. The analysis meta data can be cleared by rocsparse_bsric0_clear().

  `rocsparse_bsric0_analysis` can share its meta data with rocsparse_sbsrilu0_analysis(), rocsparse_dbsrilu0_analysis(), rocsparse_cbsrilu0_analysis(), rocsparse_zbsrilu0_analysis(), rocsparse_sbsrsv_analysis(), rocsparse_dbsrsv_analysis(), rocsparse_cbsrsv_analysis(), rocsparse_zbsrsv_analysis(), rocsparse_sbsrsm_analysis(), rocsparse_dbsrsm_analysis(), rocsparse_cbsrsm_analysis() and rocsparse_zbsrsm_analysis(). Selecting rocsparse_analysis_policy_reuse policy can greatly improve computation performance of meta data. However, the user need to make sure that the sparsity pattern remains unchanged. If this cannot be assured, rocsparse_analysis_policy_force has to be used.

  Note

  If the matrix sparsity pattern changes, the gathered information will become invalid.

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - dir – [in] direction that specified whether to count nonzero elements by rocsparse_direction_row or by rocsparse_direction_row.

    - mb – [in] number of block rows in the sparse BSR matrix.

    - nnzb – [in] number of non-zero block entries of the sparse BSR matrix.

    - descr – [in] descriptor of the sparse BSR matrix.

    - bsr_val – [in] array of length `nnzb*block_dim*block_dim` containing the values of the sparse BSR matrix.

    - bsr_row_ptr – [in] array of `mb+1` elements that point to the start of every block row of the sparse BSR matrix.

    - bsr_col_ind – [in] array of `nnzb` elements containing the block column indices of the sparse BSR matrix.

    - block_dim – [in] the block dimension of the BSR matrix. Between 1 and m where `m=mb*block_dim`.

    - info – [out] structure that holds the information collected during the analysis step.

    - analysis – [in] rocsparse_analysis_policy_reuse or rocsparse_analysis_policy_force.

    - solve – [in] rocsparse_solve_policy_auto.

    - temp_buffer – [in] temporary storage buffer allocated by the user.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `mb`, `nnzb`, or `block_dim` is invalid.

    - rocsparse_status_invalid_pointer – `descr`, `bsr_val`, `bsr_row_ptr`, `bsr_col_ind`, `info` or `temp_buffer` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

    - rocsparse_status_not_implemented – rocsparse_matrix_type != rocsparse_matrix_type_general.

### rocsparse_bsric0()

rocsparse_status rocsparse_sbsric0(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nnzb, const rocsparse_mat_descr descr, float *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, rocsparse_solve_policy policy, void *temp_buffer)

rocsparse_status rocsparse_dbsric0(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nnzb, const rocsparse_mat_descr descr, double *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, rocsparse_solve_policy policy, void *temp_buffer)

rocsparse_status rocsparse_cbsric0(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nnzb, const rocsparse_mat_descr descr, rocsparse_float_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, rocsparse_solve_policy policy, void *temp_buffer)

rocsparse_status rocsparse_zbsric0(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nnzb, const rocsparse_mat_descr descr, rocsparse_double_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, rocsparse_solve_policy policy, void *temp_buffer)

  Incomplete Cholesky factorization with 0 fill-ins and no pivoting using BSR storage format.

  `rocsparse_bsric0` computes the incomplete Cholesky factorization with 0 fill-ins and no pivoting of a sparse \(mb \times mb\) BSR matrix \(A\), such that

  \[ A \approx LL^T \]

  `rocsparse_bsric0` requires a user allocated temporary buffer. Its size is returned by rocsparse_sbsric0_buffer_size(), rocsparse_dbsric0_buffer_size(), rocsparse_cbsric0_buffer_size() or rocsparse_zbsric0_buffer_size(). Furthermore, analysis meta data is required. It can be obtained by rocsparse_sbsric0_analysis(), rocsparse_dbsric0_analysis(), rocsparse_cbsric0_analysis() or rocsparse_zbsric0_analysis(). `rocsparse_bsric0` reports the first zero pivot (either numerical or structural zero). The zero pivot status can be obtained by calling rocsparse_bsric0_zero_pivot().

  Example

    Consider the sparse \(m \times m\) matrix \(A\), stored in BSR storage format. The following example computes the incomplete Cholesky factorization \(M \approx LL^T\) and solves the preconditioned system \(My = x\).

        // Create rocSPARSE handle
        rocsparse_handle handle;
        rocsparse_create_handle(&handle);

        // Create matrix descriptor for M
        rocsparse_mat_descr descr_M;
        rocsparse_create_mat_descr(&descr_M);

        // Create matrix descriptor for L
        rocsparse_mat_descr descr_L;
        rocsparse_create_mat_descr(&descr_L);
        rocsparse_set_mat_fill_mode(descr_L, rocsparse_fill_mode_lower);
        rocsparse_set_mat_diag_type(descr_L, rocsparse_diag_type_unit);

        // Create matrix descriptor for L'
        rocsparse_mat_descr descr_Lt;
        rocsparse_create_mat_descr(&descr_Lt);
        rocsparse_set_mat_fill_mode(descr_Lt, rocsparse_fill_mode_upper);
        rocsparse_set_mat_diag_type(descr_Lt, rocsparse_diag_type_non_unit);

        // Create matrix info structure
        rocsparse_mat_info info;
        rocsparse_create_mat_info(&info);

        // Obtain required buffer size
        size_t buffer_size_M;
        size_t buffer_size_L;
        size_t buffer_size_Lt;
        rocsparse_dbsric0_buffer_size(handle,
                                       rocsparse_direction_row,
                                       mb,
                                       nnzb,
                                       descr_M,
                                       bsr_val,
                                       bsr_row_ptr,
                                       bsr_col_ind,
                                       block_dim,
                                       info,
                                       &buffer_size_M);
        rocsparse_dbsrsv_buffer_size(handle,
                                     rocsparse_direction_row,
                                     rocsparse_operation_none,
                                     mb,
                                     nnzb,
                                     descr_L,
                                     bsr_val,
                                     bsr_row_ptr,
                                     bsr_col_ind,
                                     block_dim,
                                     info,
                                     &buffer_size_L);
        rocsparse_dbsrsv_buffer_size(handle,
                                     rocsparse_direction_row,
                                     rocsparse_operation_transpose,
                                     mb,
                                     nnzb,
                                     descr_Lt,
                                     bsr_val,
                                     bsr_row_ptr,
                                     bsr_col_ind,
                                     block_dim,
                                     info,
                                     &buffer_size_Lt);

        size_t buffer_size = max(buffer_size_M, max(buffer_size_L, buffer_size_Lt));

        // Allocate temporary buffer
        void* temp_buffer;
        hipMalloc(&temp_buffer, buffer_size);

        // Perform analysis steps, using rocsparse_analysis_policy_reuse to improve
        // computation performance
        rocsparse_dbsric0_analysis(handle,
                                    rocsparse_direction_row,
                                    mb,
                                    nnzb,
                                    descr_M,
                                    bsr_val,
                                    bsr_row_ptr,
                                    bsr_col_ind,
                                    block_dim,
                                    info,
                                    rocsparse_analysis_policy_reuse,
                                    rocsparse_solve_policy_auto,
                                    temp_buffer);
        rocsparse_dbsrsv_analysis(handle,
                                  rocsparse_direction_row,
                                  rocsparse_operation_none,
                                  mb,
                                  nnzb,
                                  descr_L,
                                  bsr_val,
                                  bsr_row_ptr,
                                  bsr_col_ind,
                                  block_dim,
                                  info,
                                  rocsparse_analysis_policy_reuse,
                                  rocsparse_solve_policy_auto,
                                  temp_buffer);
        rocsparse_dbsrsv_analysis(handle,
                                  rocsparse_direction_row,
                                  rocsparse_operation_transpose,
                                  mb,
                                  nnzb,
                                  descr_Lt,
                                  bsr_val,
                                  bsr_row_ptr,
                                  bsr_col_ind,
                                  block_dim,
                                  info,
                                  rocsparse_analysis_policy_reuse,
                                  rocsparse_solve_policy_auto,
                                  temp_buffer);

        // Check for zero pivot
        rocsparse_int position;
        if(rocsparse_status_zero_pivot == rocsparse_bsric0_zero_pivot(handle,
                                                                      info,
                                                                      &position))
        {
            printf("A has structural zero at A(%d,%d)\n", position, position);
        }

        // Compute incomplete Cholesky factorization M = LL'
        rocsparse_dbsric0(handle,
                           rocsparse_direction_row,
                           mb,
                           nnzb,
                           descr_M,
                           bsr_val,
                           bsr_row_ptr,
                           bsr_col_ind,
                           block_dim,
                           info,
                           rocsparse_solve_policy_auto,
                           temp_buffer);

        // Check for zero pivot
        if(rocsparse_status_zero_pivot == rocsparse_bsric0_zero_pivot(handle,
                                                                       info,
                                                                       &position))
        {
            printf("L has structural and/or numerical zero at L(%d,%d)\n",
                   position,
                   position);
        }

        // Solve Lz = x
        rocsparse_dbsrsv_solve(handle,
                               rocsparse_direction_row,
                               rocsparse_operation_none,
                               mb,
                               nnzb,
                               &alpha,
                               descr_L,
                               bsr_val,
                               bsr_row_ptr,
                               bsr_col_ind,
                               block_dim,
                               info,
                               x,
                               z,
                               rocsparse_solve_policy_auto,
                               temp_buffer);

        // Solve L'y = z
        rocsparse_dbsrsv_solve(handle,
                               rocsparse_direction_row,
                               rocsparse_operation_transpose,
                               mb,
                               nnzb,
                               &alpha,
                               descr_Lt,
                               bsr_val,
                               bsr_row_ptr,
                               bsr_col_ind,
                               block_dim,
                               info,
                               z,
                               y,
                               rocsparse_solve_policy_auto,
                               temp_buffer);

        // Clean up
        hipFree(temp_buffer);
        rocsparse_destroy_mat_info(info);
        rocsparse_destroy_mat_descr(descr_M);
        rocsparse_destroy_mat_descr(descr_L);
        rocsparse_destroy_mat_descr(descr_Lt);
        rocsparse_destroy_handle(handle);

  Note

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

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - dir – [in] direction that specified whether to count nonzero elements by rocsparse_direction_row or by rocsparse_direction_row.

    - mb – [in] number of block rows in the sparse BSR matrix.

    - nnzb – [in] number of non-zero block entries of the sparse BSR matrix.

    - descr – [in] descriptor of the sparse BSR matrix.

    - bsr_val – [inout] array of length `nnzb*block_dim*block_dim` containing the values of the sparse BSR matrix.

    - bsr_row_ptr – [in] array of `mb+1` elements that point to the start of every block row of the sparse BSR matrix.

    - bsr_col_ind – [in] array of `nnzb` elements containing the block column indices of the sparse BSR matrix.

    - block_dim – [in] the block dimension of the BSR matrix. Between 1 and m where `m=mb*block_dim`.

    - info – [in] structure that holds the information collected during the analysis step.

    - policy – [in] rocsparse_solve_policy_auto.

    - temp_buffer – [in] temporary storage buffer allocated by the user.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `mb`, `nnzb`, or `block_dim` is invalid.

    - rocsparse_status_invalid_pointer – `descr`, `bsr_val`, `bsr_row_ptr` or `bsr_col_ind` pointer is invalid.

    - rocsparse_status_arch_mismatch – the device is not supported.

    - rocsparse_status_internal_error – an internal error occurred.

    - rocsparse_status_not_implemented – rocsparse_matrix_type != rocsparse_matrix_type_general.

### rocsparse_bsric0_clear()

rocsparse_status rocsparse_bsric0_clear(rocsparse_handle handle, rocsparse_mat_info info)

  Incomplete Cholesky factorization with 0 fill-ins and no pivoting using BSR storage format.

  `rocsparse_bsric0_clear` deallocates all memory that was allocated by rocsparse_sbsric0_analysis(), rocsparse_dbsric0_analysis(), rocsparse_cbsric0_analysis() or rocsparse_zbsric0_analysis(). This is especially useful, if memory is an issue and the analysis data is not required for further computation.

  Note

  Calling `rocsparse_bsric0_clear` is optional. All allocated resources will be cleared, when the opaque rocsparse_mat_info struct is destroyed using rocsparse_destroy_mat_info().

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - info – [inout] structure that holds the information collected during the analysis step.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_pointer – `info` pointer is invalid.

    - rocsparse_status_memory_error – the buffer holding the meta data could not be deallocated.

    - rocsparse_status_internal_error – an internal error occurred.

### rocsparse_bsrilu0_zero_pivot()

rocsparse_status rocsparse_bsrilu0_zero_pivot(rocsparse_handle handle, rocsparse_mat_info info, rocsparse_int *position)

  Incomplete LU factorization with 0 fill-ins and no pivoting using BSR storage format.

  `rocsparse_bsrilu0_zero_pivot` returns rocsparse_status_zero_pivot, if either a structural or numerical zero has been found during rocsparse_sbsrilu0(), rocsparse_dbsrilu0(), rocsparse_cbsrilu0() or rocsparse_zbsrilu0() computation. The first zero pivot \(j\) at \(A_{j,j}\) is stored in `position`, using same index base as the BSR matrix.

  `position` can be in host or device memory. If no zero pivot has been found, `position` is set to -1 and rocsparse_status_success is returned instead.

  Note

  If a zero pivot is found, `position` \(=j\) means that either the diagonal block \(A_{j,j}\) is missing (structural zero) or the diagonal block \(A_{j,j}\) is not invertible (numerical zero).

  Note

  `rocsparse_bsrilu0_zero_pivot` is a blocking function. It might influence performance negatively.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - info – [in] structure that holds the information collected during the analysis step.

    - position – [inout] pointer to zero pivot \(j\), can be in host or device memory.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_pointer – `info` or `position` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

    - rocsparse_status_zero_pivot – zero pivot has been found.

### rocsparse_bsrilu0_numeric_boost()

rocsparse_status rocsparse_sbsrilu0_numeric_boost(rocsparse_handle handle, rocsparse_mat_info info, int enable_boost, const float *boost_tol, const float *boost_val)

rocsparse_status rocsparse_dbsrilu0_numeric_boost(rocsparse_handle handle, rocsparse_mat_info info, int enable_boost, const double *boost_tol, const double *boost_val)

rocsparse_status rocsparse_cbsrilu0_numeric_boost(rocsparse_handle handle, rocsparse_mat_info info, int enable_boost, const float *boost_tol, const rocsparse_float_complex *boost_val)

rocsparse_status rocsparse_zbsrilu0_numeric_boost(rocsparse_handle handle, rocsparse_mat_info info, int enable_boost, const double *boost_tol, const rocsparse_double_complex *boost_val)

  Incomplete LU factorization with 0 fill-ins and no pivoting using BSR storage format.

  `rocsparse_bsrilu0_numeric_boost` enables the user to replace a numerical value in an incomplete LU factorization. `tol` is used to determine whether a numerical value is replaced by `boost_val`, such that \(A_{j,j} = \text{boost_val}\) if \(\text{tol} \ge \left|A_{j,j}\right|\).

  Note

  The boost value is enabled by setting `enable_boost` to 1 or disabled by setting `enable_boost` to 0.

  Note

  `tol` and `boost_val` can be in host or device memory.

  Note

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

  Note

  This routine supports execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - info – [in] structure that holds the information collected during the analysis step.

    - enable_boost – [in] enable/disable numeric boost.

    - boost_tol – [in] tolerance to determine whether a numerical value is replaced or not.

    - boost_val – [in] boost value to replace a numerical value.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_pointer – `info`, `tol` or `boost_val` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

### rocsparse_bsrilu0_buffer_size()

rocsparse_status rocsparse_sbsrilu0_buffer_size(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nnzb, const rocsparse_mat_descr descr, const float *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, size_t *buffer_size)

rocsparse_status rocsparse_dbsrilu0_buffer_size(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nnzb, const rocsparse_mat_descr descr, const double *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, size_t *buffer_size)

rocsparse_status rocsparse_cbsrilu0_buffer_size(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nnzb, const rocsparse_mat_descr descr, const rocsparse_float_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, size_t *buffer_size)

rocsparse_status rocsparse_zbsrilu0_buffer_size(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nnzb, const rocsparse_mat_descr descr, const rocsparse_double_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, size_t *buffer_size)

  Incomplete LU factorization with 0 fill-ins and no pivoting using BSR storage format.

  `rocsparse_bsrilu0_buffer_size` returns the size of the temporary storage buffer that is required by rocsparse_sbsrilu0_analysis(), rocsparse_dbsrilu0_analysis(), rocsparse_cbsrilu0_analysis(), rocsparse_zbsrilu0_analysis(), rocsparse_sbsrilu0(), rocsparse_dbsrilu0(), rocsparse_sbsrilu0() and rocsparse_dbsrilu0(). The temporary storage buffer must be allocated by the user. The size of the temporary storage buffer is identical to the size returned by rocsparse_sbsrsv_buffer_size(), rocsparse_dbsrsv_buffer_size(), rocsparse_cbsrsv_buffer_size(), rocsparse_zbsrsv_buffer_size(), rocsparse_sbsric0_buffer_size(), rocsparse_dbsric0_buffer_size(), rocsparse_cbsric0_buffer_size() and rocsparse_zbsric0_buffer_size() if the matrix sparsity pattern is identical. The user allocated buffer can thus be shared between subsequent calls to those functions.

  Note

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

  Note

  This routine supports execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - dir – [in] direction that specifies whether to count nonzero elements by rocsparse_direction_row or by rocsparse_direction_row.

    - mb – [in] number of block rows in the sparse BSR matrix.

    - nnzb – [in] number of non-zero block entries of the sparse BSR matrix.

    - descr – [in] descriptor of the sparse BSR matrix.

    - bsr_val – [in] array of length `nnzb*block_dim*block_dim` containing the values of the sparse BSR matrix.

    - bsr_row_ptr – [in] array of `mb+1` elements that point to the start of every block row of the sparse BSR matrix.

    - bsr_col_ind – [in] array of `nnzb` elements containing the block column indices of the sparse BSR matrix.

    - block_dim – [in] the block dimension of the BSR matrix. Between 1 and m where `m=mb*block_dim`.

    - info – [out] structure that holds the information collected during the analysis step.

    - buffer_size – [out] number of bytes of the temporary storage buffer required by rocsparse_sbsrilu0_analysis(), rocsparse_dbsrilu0_analysis(), rocsparse_cbsrilu0_analysis(), rocsparse_zbsrilu0_analysis(), rocsparse_sbsrilu0(), rocsparse_dbsrilu0(), rocsparse_cbsrilu0() and rocsparse_zbsrilu0().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `mb`, `nnzb`, or `block_dim` is invalid.

    - rocsparse_status_invalid_pointer – `descr`, `bsr_val`, `bsr_row_ptr`, `bsr_col_ind`, `info` or `buffer_size` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

    - rocsparse_status_not_implemented – rocsparse_matrix_type != rocsparse_matrix_type_general.

### rocsparse_bsrilu0_analysis()

rocsparse_status rocsparse_sbsrilu0_analysis(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nnzb, const rocsparse_mat_descr descr, const float *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, rocsparse_analysis_policy analysis, rocsparse_solve_policy solve, void *temp_buffer)

rocsparse_status rocsparse_dbsrilu0_analysis(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nnzb, const rocsparse_mat_descr descr, const double *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, rocsparse_analysis_policy analysis, rocsparse_solve_policy solve, void *temp_buffer)

rocsparse_status rocsparse_cbsrilu0_analysis(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nnzb, const rocsparse_mat_descr descr, const rocsparse_float_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, rocsparse_analysis_policy analysis, rocsparse_solve_policy solve, void *temp_buffer)

rocsparse_status rocsparse_zbsrilu0_analysis(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nnzb, const rocsparse_mat_descr descr, const rocsparse_double_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, rocsparse_analysis_policy analysis, rocsparse_solve_policy solve, void *temp_buffer)

  Incomplete LU factorization with 0 fill-ins and no pivoting using BSR storage format.

  `rocsparse_bsrilu0_analysis` performs the analysis step for rocsparse_sbsrilu0() rocsparse_dbsrilu0(), rocsparse_cbsrilu0(), and rocsparse_zbsrilu0(). It is expected that this function will be executed only once for a given matrix. The analysis meta data can be cleared by rocsparse_bsrilu0_clear().

  `rocsparse_bsrilu0_analysis` can share its meta data with rocsparse_sbsric0_analysis(), rocsparse_dbsric0_analysis(), rocsparse_cbsric0_analysis(), rocsparse_zbsric0_analysis(), rocsparse_sbsrsv_analysis(), rocsparse_dbsrsv_analysis(), rocsparse_cbsrsv_analysis(), rocsparse_zbsrsv_analysis(), rocsparse_sbsrsm_analysis(), rocsparse_dbsrsm_analysis(), rocsparse_cbsrsm_analysis() and rocsparse_zbsrsm_analysis(). Selecting rocsparse_analysis_policy_reuse policy can greatly improve computation performance of meta data. However, the user need to make sure that the sparsity pattern remains unchanged. If this cannot be assured, rocsparse_analysis_policy_force has to be used.

  Note

  If the matrix sparsity pattern changes, the gathered information will become invalid.

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - dir – [in] direction that specified whether to count nonzero elements by rocsparse_direction_row or by rocsparse_direction_row.

    - mb – [in] number of block rows in the sparse BSR matrix.

    - nnzb – [in] number of non-zero block entries of the sparse BSR matrix.

    - descr – [in] descriptor of the sparse BSR matrix.

    - bsr_val – [in] array of length `nnzb*block_dim*block_dim` containing the values of the sparse BSR matrix.

    - bsr_row_ptr – [in] array of `mb+1` elements that point to the start of every block row of the sparse BSR matrix.

    - bsr_col_ind – [in] array of `nnzb` elements containing the block column indices of the sparse BSR matrix.

    - block_dim – [in] the block dimension of the BSR matrix. Between 1 and m where `m=mb*block_dim`.

    - info – [out] structure that holds the information collected during the analysis step.

    - analysis – [in] rocsparse_analysis_policy_reuse or rocsparse_analysis_policy_force.

    - solve – [in] rocsparse_solve_policy_auto.

    - temp_buffer – [in] temporary storage buffer allocated by the user.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `mb`, `nnzb`, or `block_dim` is invalid.

    - rocsparse_status_invalid_pointer – `descr`, `bsr_val`, `bsr_row_ptr`, `bsr_col_ind`, `info` or `temp_buffer` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

    - rocsparse_status_not_implemented – rocsparse_matrix_type != rocsparse_matrix_type_general.

### rocsparse_bsrilu0()

rocsparse_status rocsparse_sbsrilu0(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nnzb, const rocsparse_mat_descr descr, float *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, rocsparse_solve_policy policy, void *temp_buffer)

rocsparse_status rocsparse_dbsrilu0(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nnzb, const rocsparse_mat_descr descr, double *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, rocsparse_solve_policy policy, void *temp_buffer)

rocsparse_status rocsparse_cbsrilu0(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nnzb, const rocsparse_mat_descr descr, rocsparse_float_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, rocsparse_solve_policy policy, void *temp_buffer)

rocsparse_status rocsparse_zbsrilu0(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nnzb, const rocsparse_mat_descr descr, rocsparse_double_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, rocsparse_mat_info info, rocsparse_solve_policy policy, void *temp_buffer)

  Incomplete LU factorization with 0 fill-ins and no pivoting using BSR storage format.

  `rocsparse_bsrilu0` computes the incomplete LU factorization with 0 fill-ins and no pivoting of a sparse \(mb \times mb\) BSR matrix \(A\), such that

  \[ A \approx LU \]

  `rocsparse_bsrilu0` requires a user allocated temporary buffer. Its size is returned by rocsparse_sbsrilu0_buffer_size(), rocsparse_dbsrilu0_buffer_size(), rocsparse_cbsrilu0_buffer_size() or rocsparse_zbsrilu0_buffer_size(). Furthermore, analysis meta data is required. It can be obtained by rocsparse_sbsrilu0_analysis(), rocsparse_dbsrilu0_analysis(), rocsparse_cbsrilu0_analysis() or rocsparse_zbsrilu0_analysis(). `rocsparse_bsrilu0` reports the first zero pivot (either numerical or structural zero). The zero pivot status can be obtained by calling rocsparse_bsrilu0_zero_pivot().

  Example

    Consider the sparse \(m \times m\) matrix \(A\), stored in BSR storage format. The following example computes the incomplete LU factorization \(M \approx LU\) and solves the preconditioned system \(My = x\).

        // Create rocSPARSE handle
        rocsparse_handle handle;
        rocsparse_create_handle(&handle);

        // Create matrix descriptor for M
        rocsparse_mat_descr descr_M;
        rocsparse_create_mat_descr(&descr_M);

        // Create matrix descriptor for L
        rocsparse_mat_descr descr_L;
        rocsparse_create_mat_descr(&descr_L);
        rocsparse_set_mat_fill_mode(descr_L, rocsparse_fill_mode_lower);
        rocsparse_set_mat_diag_type(descr_L, rocsparse_diag_type_unit);

        // Create matrix descriptor for U
        rocsparse_mat_descr descr_U;
        rocsparse_create_mat_descr(&descr_U);
        rocsparse_set_mat_fill_mode(descr_U, rocsparse_fill_mode_upper);
        rocsparse_set_mat_diag_type(descr_U, rocsparse_diag_type_non_unit);

        // Create matrix info structure
        rocsparse_mat_info info;
        rocsparse_create_mat_info(&info);

        // Obtain required buffer size
        size_t buffer_size_M;
        size_t buffer_size_L;
        size_t buffer_size_U;
        rocsparse_dbsrilu0_buffer_size(handle,
                                       rocsparse_direction_row,
                                       mb,
                                       nnzb,
                                       descr_M,
                                       bsr_val,
                                       bsr_row_ptr,
                                       bsr_col_ind,
                                       block_dim,
                                       info,
                                       &buffer_size_M);
        rocsparse_dbsrsv_buffer_size(handle,
                                     rocsparse_direction_row,
                                     rocsparse_operation_none,
                                     mb,
                                     nnzb,
                                     descr_L,
                                     bsr_val,
                                     bsr_row_ptr,
                                     bsr_col_ind,
                                     block_dim,
                                     info,
                                     &buffer_size_L);
        rocsparse_dbsrsv_buffer_size(handle,
                                     rocsparse_direction_row,
                                     rocsparse_operation_none,
                                     mb,
                                     nnzb,
                                     descr_U,
                                     bsr_val,
                                     bsr_row_ptr,
                                     bsr_col_ind,
                                     block_dim,
                                     info,
                                     &buffer_size_U);

        size_t buffer_size = max(buffer_size_M, max(buffer_size_L, buffer_size_U));

        // Allocate temporary buffer
        void* temp_buffer;
        hipMalloc(&temp_buffer, buffer_size);

        // Perform analysis steps, using rocsparse_analysis_policy_reuse to improve
        // computation performance
        rocsparse_dbsrilu0_analysis(handle,
                                    rocsparse_direction_row,
                                    mb,
                                    nnzb,
                                    descr_M,
                                    bsr_val,
                                    bsr_row_ptr,
                                    bsr_col_ind,
                                    block_dim,
                                    info,
                                    rocsparse_analysis_policy_reuse,
                                    rocsparse_solve_policy_auto,
                                    temp_buffer);
        rocsparse_dbsrsv_analysis(handle,
                                  rocsparse_direction_row,
                                  rocsparse_operation_none,
                                  mb,
                                  nnzb,
                                  descr_L,
                                  bsr_val,
                                  bsr_row_ptr,
                                  bsr_col_ind,
                                  block_dim,
                                  info,
                                  rocsparse_analysis_policy_reuse,
                                  rocsparse_solve_policy_auto,
                                  temp_buffer);
        rocsparse_dbsrsv_analysis(handle,
                                  rocsparse_direction_row,
                                  rocsparse_operation_none,
                                  mb,
                                  nnzb,
                                  descr_U,
                                  bsr_val,
                                  bsr_row_ptr,
                                  bsr_col_ind,
                                  block_dim,
                                  info,
                                  rocsparse_analysis_policy_reuse,
                                  rocsparse_solve_policy_auto,
                                  temp_buffer);

        // Check for zero pivot
        rocsparse_int position;
        if(rocsparse_status_zero_pivot == rocsparse_bsrilu0_zero_pivot(handle,
                                                                      info,
                                                                      &position))
        {
            printf("A has structural zero at A(%d,%d)\n", position, position);
        }

        // Compute incomplete LU factorization M = LU
        rocsparse_dbsrilu0(handle,
                           rocsparse_direction_row,
                           mb,
                           nnzb,
                           descr_M,
                           bsr_val,
                           bsr_row_ptr,
                           bsr_col_ind,
                           block_dim,
                           info,
                           rocsparse_solve_policy_auto,
                           temp_buffer);

        // Check for zero pivot
        if(rocsparse_status_zero_pivot == rocsparse_bsrilu0_zero_pivot(handle,
                                                                       info,
                                                                       &position))
        {
            printf("L has structural and/or numerical zero at L(%d,%d)\n",
                   position,
                   position);
        }

        // Solve Lz = x
        rocsparse_dbsrsv_solve(handle,
                               rocsparse_direction_row,
                               rocsparse_operation_none,
                               mb,
                               nnzb,
                               &alpha,
                               descr_L,
                               bsr_val,
                               bsr_row_ptr,
                               bsr_col_ind,
                               block_dim,
                               info,
                               x,
                               z,
                               rocsparse_solve_policy_auto,
                               temp_buffer);

        // Solve Uy = z
        rocsparse_dbsrsv_solve(handle,
                               rocsparse_direction_row,
                               rocsparse_operation_none,
                               mb,
                               nnzb,
                               &alpha,
                               descr_U,
                               bsr_val,
                               bsr_row_ptr,
                               bsr_col_ind,
                               block_dim,
                               info,
                               z,
                               y,
                               rocsparse_solve_policy_auto,
                               temp_buffer);

        // Clean up
        hipFree(temp_buffer);
        rocsparse_destroy_mat_info(info);
        rocsparse_destroy_mat_descr(descr_M);
        rocsparse_destroy_mat_descr(descr_L);
        rocsparse_destroy_mat_descr(descr_U);
        rocsparse_destroy_handle(handle);

  Note

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

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - dir – [in] direction that specified whether to count nonzero elements by rocsparse_direction_row or by rocsparse_direction_row.

    - mb – [in] number of block rows in the sparse BSR matrix.

    - nnzb – [in] number of non-zero block entries of the sparse BSR matrix.

    - descr – [in] descriptor of the sparse BSR matrix.

    - bsr_val – [inout] array of length `nnzb*block_dim*block_dim` containing the values of the sparse BSR matrix.

    - bsr_row_ptr – [in] array of `mb+1` elements that point to the start of every block row of the sparse BSR matrix.

    - bsr_col_ind – [in] array of `nnzb` elements containing the block column indices of the sparse BSR matrix.

    - block_dim – [in] the block dimension of the BSR matrix. Between 1 and m where `m=mb*block_dim`.

    - info – [in] structure that holds the information collected during the analysis step.

    - policy – [in] rocsparse_solve_policy_auto.

    - temp_buffer – [in] temporary storage buffer allocated by the user.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `mb`, `nnzb`, or `block_dim` is invalid.

    - rocsparse_status_invalid_pointer – `descr`, `bsr_val`, `bsr_row_ptr` or `bsr_col_ind` pointer is invalid.

    - rocsparse_status_arch_mismatch – the device is not supported.

    - rocsparse_status_internal_error – an internal error occurred.

    - rocsparse_status_not_implemented – rocsparse_matrix_type != rocsparse_matrix_type_general.

### rocsparse_bsrilu0_clear()

rocsparse_status rocsparse_bsrilu0_clear(rocsparse_handle handle, rocsparse_mat_info info)

  Incomplete LU factorization with 0 fill-ins and no pivoting using BSR storage format.

  `rocsparse_bsrilu0_clear` deallocates all memory that was allocated by rocsparse_sbsrilu0_analysis(), rocsparse_dbsrilu0_analysis(), rocsparse_cbsrilu0_analysis() or rocsparse_zbsrilu0_analysis(). This is especially useful, if memory is an issue and the analysis data is not required for further computation.

  Note

  Calling `rocsparse_bsrilu0_clear` is optional. All allocated resources will be cleared, when the opaque rocsparse_mat_info struct is destroyed using rocsparse_destroy_mat_info().

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - info – [inout] structure that holds the information collected during the analysis step.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_pointer – `info` pointer is invalid.

    - rocsparse_status_memory_error – the buffer holding the meta data could not be deallocated.

    - rocsparse_status_internal_error – an internal error occurred.

### rocsparse_csric0_zero_pivot()

rocsparse_status rocsparse_csric0_zero_pivot(rocsparse_handle handle, rocsparse_mat_info info, rocsparse_int *position)

  Incomplete Cholesky factorization with 0 fill-ins and no pivoting using CSR storage format.

  `rocsparse_csric_zero_pivot` returns rocsparse_status_zero_pivot, if either a structural or numerical zero has been found during rocsparse_scsric0() or rocsparse_dcsric0() computation. The first zero pivot \(j\) at \(A_{j,j}\) is stored in `position`, using same index base as the CSR matrix.

  `position` can be in host or device memory. If no zero pivot has been found, `position` is set to -1 and rocsparse_status_success is returned instead.

  Note

  `rocsparse_csric0_zero_pivot` is a blocking function. It might influence performance negatively.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - info – [in] structure that holds the information collected during the analysis step.

    - position – [inout] pointer to zero pivot \(j\), can be in host or device memory.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_pointer – `info` or `position` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

    - rocsparse_status_zero_pivot – zero pivot has been found.

### rocsparse_csric0_buffer_size()

rocsparse_status rocsparse_scsric0_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int nnz, const rocsparse_mat_descr descr, const float *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, size_t *buffer_size)

rocsparse_status rocsparse_dcsric0_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int nnz, const rocsparse_mat_descr descr, const double *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, size_t *buffer_size)

rocsparse_status rocsparse_ccsric0_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int nnz, const rocsparse_mat_descr descr, const rocsparse_float_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, size_t *buffer_size)

rocsparse_status rocsparse_zcsric0_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int nnz, const rocsparse_mat_descr descr, const rocsparse_double_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, size_t *buffer_size)

  Incomplete Cholesky factorization with 0 fill-ins and no pivoting using CSR storage format.

  `rocsparse_csric0_buffer_size` returns the size of the temporary storage buffer that is required by rocsparse_scsric0_analysis(), rocsparse_dcsric0_analysis(), rocsparse_scsric0() and rocsparse_dcsric0(). The temporary storage buffer must be allocated by the user. The size of the temporary storage buffer is identical to the size returned by rocsparse_scsrsv_buffer_size(), rocsparse_dcsrsv_buffer_size(), rocsparse_scsrilu0_buffer_size() and rocsparse_dcsrilu0_buffer_size() if the matrix sparsity pattern is identical. The user allocated buffer can thus be shared between subsequent calls to those functions.

  Note

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

  Note

  This routine supports execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows of the sparse CSR matrix.

    - nnz – [in] number of non-zero entries of the sparse CSR matrix.

    - descr – [in] descriptor of the sparse CSR matrix.

    - csr_val – [in] array of `nnz` elements of the sparse CSR matrix.

    - csr_row_ptr – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix.

    - csr_col_ind – [in] array of `nnz` elements containing the column indices of the sparse CSR matrix.

    - info – [out] structure that holds the information collected during the analysis step.

    - buffer_size – [out] number of bytes of the temporary storage buffer required by rocsparse_scsric0_analysis(), rocsparse_dcsric0_analysis(), rocsparse_scsric0() and rocsparse_dcsric0().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m` or `nnz` is invalid.

    - rocsparse_status_invalid_pointer – `descr`, `csr_val`, `csr_row_ptr`, `csr_col_ind`, `info` or `buffer_size` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

    - rocsparse_status_not_implemented – `trans` != rocsparse_operation_none or rocsparse_matrix_type != rocsparse_matrix_type_general.

### rocsparse_csric0_analysis()

rocsparse_status rocsparse_scsric0_analysis(rocsparse_handle handle, rocsparse_int m, rocsparse_int nnz, const rocsparse_mat_descr descr, const float *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, rocsparse_analysis_policy analysis, rocsparse_solve_policy solve, void *temp_buffer)

rocsparse_status rocsparse_dcsric0_analysis(rocsparse_handle handle, rocsparse_int m, rocsparse_int nnz, const rocsparse_mat_descr descr, const double *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, rocsparse_analysis_policy analysis, rocsparse_solve_policy solve, void *temp_buffer)

rocsparse_status rocsparse_ccsric0_analysis(rocsparse_handle handle, rocsparse_int m, rocsparse_int nnz, const rocsparse_mat_descr descr, const rocsparse_float_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, rocsparse_analysis_policy analysis, rocsparse_solve_policy solve, void *temp_buffer)

rocsparse_status rocsparse_zcsric0_analysis(rocsparse_handle handle, rocsparse_int m, rocsparse_int nnz, const rocsparse_mat_descr descr, const rocsparse_double_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, rocsparse_analysis_policy analysis, rocsparse_solve_policy solve, void *temp_buffer)

  Incomplete Cholesky factorization with 0 fill-ins and no pivoting using CSR storage format.

  `rocsparse_csric0_analysis` performs the analysis step for rocsparse_scsric0() and rocsparse_dcsric0(). It is expected that this function will be executed only once for a given matrix and particular operation type. The analysis meta data can be cleared by rocsparse_csric0_clear().

  `rocsparse_csric0_analysis` can share its meta data with rocsparse_scsrilu0_analysis(), rocsparse_dcsrilu0_analysis(), rocsparse_ccsrilu0_analysis(), rocsparse_zcsrilu0_analysis(), rocsparse_scsrsv_analysis(), rocsparse_dcsrsv_analysis(), rocsparse_ccsrsv_analysis(), rocsparse_zcsrsv_analysis(), rocsparse_scsrsm_analysis(), rocsparse_dcsrsm_analysis(), rocsparse_scsrsm_analysis() and rocsparse_dcsrsm_analysis(). Selecting rocsparse_analysis_policy_reuse policy can greatly improve computation performance of meta data. However, the user need to make sure that the sparsity pattern remains unchanged. If this cannot be assured, rocsparse_analysis_policy_force has to be used.

  Note

  If the matrix sparsity pattern changes, the gathered information will become invalid.

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows of the sparse CSR matrix.

    - nnz – [in] number of non-zero entries of the sparse CSR matrix.

    - descr – [in] descriptor of the sparse CSR matrix.

    - csr_val – [in] array of `nnz` elements of the sparse CSR matrix.

    - csr_row_ptr – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix.

    - csr_col_ind – [in] array of `nnz` elements containing the column indices of the sparse CSR matrix.

    - info – [out] structure that holds the information collected during the analysis step.

    - analysis – [in] rocsparse_analysis_policy_reuse or rocsparse_analysis_policy_force.

    - solve – [in] rocsparse_solve_policy_auto.

    - temp_buffer – [in] temporary storage buffer allocated by the user.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m` or `nnz` is invalid.

    - rocsparse_status_invalid_pointer – `descr`, `csr_val`, `csr_row_ptr`, `csr_col_ind`, `info` or `temp_buffer` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

    - rocsparse_status_not_implemented – `trans` != rocsparse_operation_none or rocsparse_matrix_type != rocsparse_matrix_type_general.

### rocsparse_csric0()

rocsparse_status rocsparse_scsric0(rocsparse_handle handle, rocsparse_int m, rocsparse_int nnz, const rocsparse_mat_descr descr, float *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, rocsparse_solve_policy policy, void *temp_buffer)

rocsparse_status rocsparse_dcsric0(rocsparse_handle handle, rocsparse_int m, rocsparse_int nnz, const rocsparse_mat_descr descr, double *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, rocsparse_solve_policy policy, void *temp_buffer)

rocsparse_status rocsparse_ccsric0(rocsparse_handle handle, rocsparse_int m, rocsparse_int nnz, const rocsparse_mat_descr descr, rocsparse_float_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, rocsparse_solve_policy policy, void *temp_buffer)

rocsparse_status rocsparse_zcsric0(rocsparse_handle handle, rocsparse_int m, rocsparse_int nnz, const rocsparse_mat_descr descr, rocsparse_double_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, rocsparse_solve_policy policy, void *temp_buffer)

  Incomplete Cholesky factorization with 0 fill-ins and no pivoting using CSR storage format.

  `rocsparse_csric0` computes the incomplete Cholesky factorization with 0 fill-ins and no pivoting of a sparse \(m \times m\) CSR matrix \(A\), such that

  \[ A \approx LL^T \]

  `rocsparse_csric0` requires a user allocated temporary buffer. Its size is returned by rocsparse_scsric0_buffer_size() or rocsparse_dcsric0_buffer_size(). Furthermore, analysis meta data is required. It can be obtained by rocsparse_scsric0_analysis() or rocsparse_dcsric0_analysis(). `rocsparse_csric0` reports the first zero pivot (either numerical or structural zero). The zero pivot status can be obtained by calling rocsparse_csric0_zero_pivot().

  Example

    Consider the sparse \(m \times m\) matrix \(A\), stored in CSR storage format. The following example computes the incomplete Cholesky factorization \(M \approx LL^T\) and solves the preconditioned system \(My = x\).

        // Create rocSPARSE handle
        rocsparse_handle handle;
        rocsparse_create_handle(&handle);

        // Create matrix descriptor for M
        rocsparse_mat_descr descr_M;
        rocsparse_create_mat_descr(&descr_M);

        // Create matrix descriptor for L
        rocsparse_mat_descr descr_L;
        rocsparse_create_mat_descr(&descr_L);
        rocsparse_set_mat_fill_mode(descr_L, rocsparse_fill_mode_lower);
        rocsparse_set_mat_diag_type(descr_L, rocsparse_diag_type_unit);

        // Create matrix descriptor for L'
        rocsparse_mat_descr descr_Lt;
        rocsparse_create_mat_descr(&descr_Lt);
        rocsparse_set_mat_fill_mode(descr_Lt, rocsparse_fill_mode_upper);
        rocsparse_set_mat_diag_type(descr_Lt, rocsparse_diag_type_non_unit);

        // Create matrix info structure
        rocsparse_mat_info info;
        rocsparse_create_mat_info(&info);

        // Obtain required buffer size
        size_t buffer_size_M;
        size_t buffer_size_L;
        size_t buffer_size_Lt;
        rocsparse_dcsric0_buffer_size(handle,
                                      m,
                                      nnz,
                                      descr_M,
                                      csr_val,
                                      csr_row_ptr,
                                      csr_col_ind,
                                      info,
                                      &buffer_size_M);
        rocsparse_dcsrsv_buffer_size(handle,
                                     rocsparse_operation_none,
                                     m,
                                     nnz,
                                     descr_L,
                                     csr_val,
                                     csr_row_ptr,
                                     csr_col_ind,
                                     info,
                                     &buffer_size_L);
        rocsparse_dcsrsv_buffer_size(handle,
                                     rocsparse_operation_transpose,
                                     m,
                                     nnz,
                                     descr_Lt,
                                     csr_val,
                                     csr_row_ptr,
                                     csr_col_ind,
                                     info,
                                     &buffer_size_Lt);

        size_t buffer_size = max(buffer_size_M, max(buffer_size_L, buffer_size_Lt));

        // Allocate temporary buffer
        void* temp_buffer;
        hipMalloc(&temp_buffer, buffer_size);

        // Perform analysis steps, using rocsparse_analysis_policy_reuse to improve
        // computation performance
        rocsparse_dcsric0_analysis(handle,
                                   m,
                                   nnz,
                                   descr_M,
                                   csr_val,
                                   csr_row_ptr,
                                   csr_col_ind,
                                   info,
                                   rocsparse_analysis_policy_reuse,
                                   rocsparse_solve_policy_auto,
                                   temp_buffer);
        rocsparse_dcsrsv_analysis(handle,
                                  rocsparse_operation_none,
                                  m,
                                  nnz,
                                  descr_L,
                                  csr_val,
                                  csr_row_ptr,
                                  csr_col_ind,
                                  info,
                                  rocsparse_analysis_policy_reuse,
                                  rocsparse_solve_policy_auto,
                                  temp_buffer);
        rocsparse_dcsrsv_analysis(handle,
                                  rocsparse_operation_transpose,
                                  m,
                                  nnz,
                                  descr_Lt,
                                  csr_val,
                                  csr_row_ptr,
                                  csr_col_ind,
                                  info,
                                  rocsparse_analysis_policy_reuse,
                                  rocsparse_solve_policy_auto,
                                  temp_buffer);

        // Check for zero pivot
        rocsparse_int position;
        if(rocsparse_status_zero_pivot == rocsparse_csric0_zero_pivot(handle,
                                                                      info,
                                                                      &position))
        {
            printf("A has structural zero at A(%d,%d)\n", position, position);
        }

        // Compute incomplete Cholesky factorization M = LL'
        rocsparse_dcsric0(handle,
                          m,
                          nnz,
                          descr_M,
                          csr_val,
                          csr_row_ptr,
                          csr_col_ind,
                          info,
                          rocsparse_solve_policy_auto,
                          temp_buffer);

        // Check for zero pivot
        if(rocsparse_status_zero_pivot == rocsparse_csric0_zero_pivot(handle,
                                                                      info,
                                                                      &position))
        {
            printf("L has structural and/or numerical zero at L(%d,%d)\n",
                   position,
                   position);
        }

        // Solve Lz = x
        rocsparse_dcsrsv_solve(handle,
                               rocsparse_operation_none,
                               m,
                               nnz,
                               &alpha,
                               descr_L,
                               csr_val,
                               csr_row_ptr,
                               csr_col_ind,
                               info,
                               x,
                               z,
                               rocsparse_solve_policy_auto,
                               temp_buffer);

        // Solve L'y = z
        rocsparse_dcsrsv_solve(handle,
                               rocsparse_operation_transpose,
                               m,
                               nnz,
                               &alpha,
                               descr_Lt,
                               csr_val,
                               csr_row_ptr,
                               csr_col_ind,
                               info,
                               z,
                               y,
                               rocsparse_solve_policy_auto,
                               temp_buffer);

        // Clean up
        hipFree(temp_buffer);
        rocsparse_destroy_mat_info(info);
        rocsparse_destroy_mat_descr(descr_M);
        rocsparse_destroy_mat_descr(descr_L);
        rocsparse_destroy_mat_descr(descr_Lt);
        rocsparse_destroy_handle(handle);

  Note

  The sparse CSR matrix has to be sorted. This can be achieved by calling rocsparse_csrsort().

  Note

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

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows of the sparse CSR matrix.

    - nnz – [in] number of non-zero entries of the sparse CSR matrix.

    - descr – [in] descriptor of the sparse CSR matrix.

    - csr_val – [inout] array of `nnz` elements of the sparse CSR matrix.

    - csr_row_ptr – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix.

    - csr_col_ind – [in] array of `nnz` elements containing the column indices of the sparse CSR matrix.

    - info – [in] structure that holds the information collected during the analysis step.

    - policy – [in] rocsparse_solve_policy_auto.

    - temp_buffer – [in] temporary storage buffer allocated by the user.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m` or `nnz` is invalid.

    - rocsparse_status_invalid_pointer – `descr`, `csr_val`, `csr_row_ptr` or `csr_col_ind` pointer is invalid.

    - rocsparse_status_arch_mismatch – the device is not supported.

    - rocsparse_status_internal_error – an internal error occurred.

    - rocsparse_status_not_implemented – `trans` != rocsparse_operation_none or rocsparse_matrix_type != rocsparse_matrix_type_general.

### rocsparse_csric0_clear()

rocsparse_status rocsparse_csric0_clear(rocsparse_handle handle, rocsparse_mat_info info)

  Incomplete Cholesky factorization with 0 fill-ins and no pivoting using CSR storage format.

  `rocsparse_csric0_clear` deallocates all memory that was allocated by rocsparse_scsric0_analysis() or rocsparse_dcsric0_analysis(). This is especially useful, if memory is an issue and the analysis data is not required for further computation.

  Note

  Calling `rocsparse_csric0_clear` is optional. All allocated resources will be cleared, when the opaque rocsparse_mat_info struct is destroyed using rocsparse_destroy_mat_info().

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - info – [inout] structure that holds the information collected during the analysis step.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_pointer – `info` pointer is invalid.

    - rocsparse_status_memory_error – the buffer holding the meta data could not be deallocated.

    - rocsparse_status_internal_error – an internal error occurred.

### rocsparse_csritilu0_buffer_size()

rocsparse_status rocsparse_csritilu0_buffer_size(rocsparse_handle handle, rocsparse_itilu0_alg alg, rocsparse_int option, rocsparse_int nmaxiter, rocsparse_int m, rocsparse_int nnz, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_index_base idx_base, rocsparse_datatype datatype, size_t *buffer_size)

  Iterative Incomplete LU factorization with 0 fill-ins and no pivoting using CSR storage format.

  `rocsparse_csritilu0_buffer_size` computes the size in bytes of the buffer that has to be allocated by the user.

  Note

  The sparse CSR matrix has to be sorted. This can be achieved by calling rocsparse_csrsort().

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - alg – [in] algorithm to use, rocsparse_itilu0_alg

    - option – [in] combination of enumeration values from rocsparse_itilu0_option.

    - nmaxiter – [in] maximum number of iterations.

    - m – [in] number of rows of the sparse CSR matrix.

    - nnz – [in] number of non-zero entries of the sparse CSR matrix.

    - csr_row_ptr – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix.

    - csr_col_ind – [in] array of `nnz` elements containing the column indices of the sparse CSR matrix.

    - idx_base – [in] rocsparse_index_base_zero or rocsparse_index_base_one.

    - datatype – [in] Type of numerical values, rocsparse_datatype.

    - buffer_size – [out] size of the temporary storage buffer allocated by the user.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m` or `nnz` is invalid.

    - rocsparse_status_invalid_value – `alg`, `base` or datatype is invalid.

    - rocsparse_status_invalid_pointer – `csr_row_ptr` or `csr_col_ind` pointer is invalid.

    - rocsparse_status_zero_pivot – if nnz is zero.

    - rocsparse_status_internal_error – an internal error occurred.

### rocsparse_csritilu0_preprocess()

rocsparse_status rocsparse_csritilu0_preprocess(rocsparse_handle handle, rocsparse_itilu0_alg alg, rocsparse_int option, rocsparse_int nmaxiter, rocsparse_int m, rocsparse_int nnz, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_index_base idx_base, rocsparse_datatype datatype, size_t buffer_size, void *buffer)

  Iterative Incomplete LU factorization with 0 fill-ins and no pivoting using CSR storage format.

  `rocsparse_csritilu0_preprocess` computes the information required to run rocsparse_scsritilu0_compute, rocsparse_dcsritilu0_compute, rocsparse_ccsritilu0_compute, or rocsparse_zcsritilu0_compute, and stores it in the buffer.

  Note

  The sparse CSR matrix has to be sorted. This can be achieved by calling rocsparse_csrsort().

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - alg – [in] algorithm to use, rocsparse_itilu0_alg

    - option – [in] combination of enumeration values from rocsparse_itilu0_option.

    - nmaxiter – [in] maximum number of iterations.

    - m – [in] number of rows of the sparse CSR matrix.

    - nnz – [in] number of non-zero entries of the sparse CSR matrix.

    - csr_row_ptr – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix.

    - csr_col_ind – [in] array of `nnz` elements containing the column indices of the sparse CSR matrix.

    - idx_base – [in] rocsparse_index_base_zero or rocsparse_index_base_one.

    - datatype – [in] Type of numerical values, rocsparse_datatype.

    - buffer_size – [in] size of the storage buffer allocated by the user.

    - buffer – [in] storage buffer allocated by the user.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_value – `alg`, `base` or datatype is invalid.

    - rocsparse_status_invalid_size – `m` or `nnz` is invalid.

    - rocsparse_status_invalid_pointer – `csr_row_ptr` or `csr_col_ind` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

    - rocsparse_status_zero_pivot – if missing diagonal element is detected.

### rocsparse_csritilu0_history()

rocsparse_status rocsparse_scsritilu0_history(rocsparse_handle handle, rocsparse_itilu0_alg alg, rocsparse_int *niter, float *data, size_t buffer_size, void *buffer)

rocsparse_status rocsparse_dcsritilu0_history(rocsparse_handle handle, rocsparse_itilu0_alg alg, rocsparse_int *niter, double *data, size_t buffer_size, void *buffer)

rocsparse_status rocsparse_ccsritilu0_history(rocsparse_handle handle, rocsparse_itilu0_alg alg, rocsparse_int *niter, float *data, size_t buffer_size, void *buffer)

rocsparse_status rocsparse_zcsritilu0_history(rocsparse_handle handle, rocsparse_itilu0_alg alg, rocsparse_int *niter, double *data, size_t buffer_size, void *buffer)

  Iterative Incomplete LU factorization with 0 fill-ins and no pivoting using CSR storage format.

  `rocsparse_csritilu0_history` fetches convergence history data.

  Note

  The sparse CSR matrix has to be sorted. This can be achieved by calling rocsparse_csrsort().

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - alg – [in] algorithm to use, rocsparse_itilu0_alg

    - niter – [out] number of performed iterations.

    - data – [out] norms.

    - buffer_size – [in] size of the buffer allocated by the user.

    - buffer – [in] buffer allocated by the user.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_pointer – `niter` or `data` is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

### rocsparse_csritilu0_compute()

rocsparse_status rocsparse_scsritilu0_compute(rocsparse_handle handle, rocsparse_itilu0_alg alg, rocsparse_int option, rocsparse_int *nmaxiter, float tol, rocsparse_int m, rocsparse_int nnz, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, const float *csr_val, float *ilu0, rocsparse_index_base idx_base, size_t buffer_size, void *buffer)

rocsparse_status rocsparse_dcsritilu0_compute(rocsparse_handle handle, rocsparse_itilu0_alg alg, rocsparse_int option, rocsparse_int *nmaxiter, double tol, rocsparse_int m, rocsparse_int nnz, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, const double *csr_val, double *ilu0, rocsparse_index_base idx_base, size_t buffer_size, void *buffer)

rocsparse_status rocsparse_ccsritilu0_compute(rocsparse_handle handle, rocsparse_itilu0_alg alg, rocsparse_int option, rocsparse_int *nmaxiter, float tol, rocsparse_int m, rocsparse_int nnz, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, const rocsparse_float_complex *csr_val, rocsparse_float_complex *ilu0, rocsparse_index_base idx_base, size_t buffer_size, void *buffer)

rocsparse_status rocsparse_zcsritilu0_compute(rocsparse_handle handle, rocsparse_itilu0_alg alg, rocsparse_int option, rocsparse_int *nmaxiter, double tol, rocsparse_int m, rocsparse_int nnz, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, const rocsparse_double_complex *csr_val, rocsparse_double_complex *ilu0, rocsparse_index_base idx_base, size_t buffer_size, void *buffer)

  Iterative Incomplete LU factorization with 0 fill-ins and no pivoting using CSR storage format.

  `rocsparse_csritilu0_compute` computes iteratively the incomplete LU factorization with 0 fill-ins and no pivoting of a sparse \(m \times m\) CSR matrix \(A\), such that

  \[ A \approx LU \]

  `rocsparse_csritilu0` requires a user allocated temporary buffer. Its size is returned by rocsparse_csritilu0_buffer_size(). Furthermore, analysis meta data is required. It can be obtained by rocsparse_csritlu0_preprocess().

  Note

  The sparse CSR matrix has to be sorted. This can be achieved by calling rocsparse_csrsort().

  Note

  This function is blocking with respect to the host.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - alg – [in] algorithm to use, rocsparse_itilu0_alg

    - option – [in] combination of enumeration values from rocsparse_itilu0_option.

    - nmaxiter – [inout] maximum number of iterations.

    - tol – [in] tolerance to use for stopping criteria.

    - m – [in] number of rows of the sparse CSR matrix.

    - nnz – [in] number of non-zero entries of the sparse CSR matrix.

    - csr_row_ptr – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix.

    - csr_col_ind – [in] array of `nnz` elements containing the column indices of the sparse CSR matrix.

    - csr_val – [inout] array of `nnz` elements of the sparse CSR matrix.

    - ilu0 – [out] incomplete factorization.

    - idx_base – [in] rocsparse_index_base_zero or rocsparse_index_base_one.

    - buffer_size – [in] size of the storage buffer allocated by the user.

    - buffer – [in] storage buffer allocated by the user.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_value – `alg` or `base` is invalid.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m` or `nnz` is invalid.

    - rocsparse_status_invalid_pointer – `csr_row_ptr` or `csr_col_ind` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

### rocsparse_csrilu0_zero_pivot()

rocsparse_status rocsparse_csrilu0_zero_pivot(rocsparse_handle handle, rocsparse_mat_info info, rocsparse_int *position)

  Incomplete LU factorization with 0 fill-ins and no pivoting using CSR storage format.

  `rocsparse_csrilu0_zero_pivot` returns rocsparse_status_zero_pivot, if either a structural or numerical zero has been found during rocsparse_scsrilu0(), rocsparse_dcsrilu0(), rocsparse_ccsrilu0() or rocsparse_zcsrilu0() computation. The first zero pivot \(j\) at \(A_{j,j}\) is stored in `position`, using same index base as the CSR matrix.

  `position` can be in host or device memory. If no zero pivot has been found, `position` is set to -1 and rocsparse_status_success is returned instead.

  Note

  `rocsparse_csrilu0_zero_pivot` is a blocking function. It might influence performance negatively.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - info – [in] structure that holds the information collected during the analysis step.

    - position – [inout] pointer to zero pivot \(j\), can be in host or device memory.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_pointer – `info` or `position` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

    - rocsparse_status_zero_pivot – zero pivot has been found.

### rocsparse_csrilu0_numeric_boost()

rocsparse_status rocsparse_scsrilu0_numeric_boost(rocsparse_handle handle, rocsparse_mat_info info, int enable_boost, const float *boost_tol, const float *boost_val)

rocsparse_status rocsparse_dcsrilu0_numeric_boost(rocsparse_handle handle, rocsparse_mat_info info, int enable_boost, const double *boost_tol, const double *boost_val)

rocsparse_status rocsparse_ccsrilu0_numeric_boost(rocsparse_handle handle, rocsparse_mat_info info, int enable_boost, const float *boost_tol, const rocsparse_float_complex *boost_val)

rocsparse_status rocsparse_zcsrilu0_numeric_boost(rocsparse_handle handle, rocsparse_mat_info info, int enable_boost, const double *boost_tol, const rocsparse_double_complex *boost_val)

  Incomplete LU factorization with 0 fill-ins and no pivoting using CSR storage format.

  `rocsparse_csrilu0_numeric_boost` enables the user to replace a numerical value in an incomplete LU factorization. `tol` is used to determine whether a numerical value is replaced by `boost_val`, such that \(A_{j,j} = \text{boost_val}\) if \(\text{tol} \ge \left|A_{j,j}\right|\).

  Note

  The boost value is enabled by setting `enable_boost` to 1 or disabled by setting `enable_boost` to 0.

  Note

  `tol` and `boost_val` can be in host or device memory.

  Note

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

  Note

  This routine supports execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - info – [in] structure that holds the information collected during the analysis step.

    - enable_boost – [in] enable/disable numeric boost.

    - boost_tol – [in] tolerance to determine whether a numerical value is replaced or not.

    - boost_val – [in] boost value to replace a numerical value.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_pointer – `info`, `tol` or `boost_val` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

### rocsparse_csrilu0_buffer_size()

rocsparse_status rocsparse_scsrilu0_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int nnz, const rocsparse_mat_descr descr, const float *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, size_t *buffer_size)

rocsparse_status rocsparse_dcsrilu0_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int nnz, const rocsparse_mat_descr descr, const double *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, size_t *buffer_size)

rocsparse_status rocsparse_ccsrilu0_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int nnz, const rocsparse_mat_descr descr, const rocsparse_float_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, size_t *buffer_size)

rocsparse_status rocsparse_zcsrilu0_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int nnz, const rocsparse_mat_descr descr, const rocsparse_double_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, size_t *buffer_size)

  Incomplete LU factorization with 0 fill-ins and no pivoting using CSR storage format.

  `rocsparse_csrilu0_buffer_size` returns the size of the temporary storage buffer that is required by rocsparse_scsrilu0_analysis(), rocsparse_dcsrilu0_analysis(), rocsparse_ccsrilu0_analysis(), rocsparse_zcsrilu0_analysis(), rocsparse_scsrilu0(), rocsparse_dcsrilu0(), rocsparse_ccsrilu0() and rocsparse_zcsrilu0(). The temporary storage buffer must be allocated by the user. The size of the temporary storage buffer is identical to the size returned by rocsparse_scsrsv_buffer_size(), rocsparse_dcsrsv_buffer_size(), rocsparse_ccsrsv_buffer_size() and rocsparse_zcsrsv_buffer_size() if the matrix sparsity pattern is identical. The user allocated buffer can thus be shared between subsequent calls to those functions.

  Note

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

  Note

  This routine supports execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows of the sparse CSR matrix.

    - nnz – [in] number of non-zero entries of the sparse CSR matrix.

    - descr – [in] descriptor of the sparse CSR matrix.

    - csr_val – [in] array of `nnz` elements of the sparse CSR matrix.

    - csr_row_ptr – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix.

    - csr_col_ind – [in] array of `nnz` elements containing the column indices of the sparse CSR matrix.

    - info – [out] structure that holds the information collected during the analysis step.

    - buffer_size – [out] number of bytes of the temporary storage buffer required by rocsparse_scsrilu0_analysis(), rocsparse_dcsrilu0_analysis(), rocsparse_ccsrilu0_analysis(), rocsparse_zcsrilu0_analysis(), rocsparse_scsrilu0(), rocsparse_dcsrilu0(), rocsparse_ccsrilu0() and rocsparse_zcsrilu0().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m` or `nnz` is invalid.

    - rocsparse_status_invalid_pointer – `descr`, `csr_val`, `csr_row_ptr`, `csr_col_ind`, `info` or `buffer_size` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

    - rocsparse_status_not_implemented – `trans` != rocsparse_operation_none or rocsparse_matrix_type != rocsparse_matrix_type_general.

### rocsparse_csrilu0_analysis()

rocsparse_status rocsparse_scsrilu0_analysis(rocsparse_handle handle, rocsparse_int m, rocsparse_int nnz, const rocsparse_mat_descr descr, const float *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, rocsparse_analysis_policy analysis, rocsparse_solve_policy solve, void *temp_buffer)

rocsparse_status rocsparse_dcsrilu0_analysis(rocsparse_handle handle, rocsparse_int m, rocsparse_int nnz, const rocsparse_mat_descr descr, const double *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, rocsparse_analysis_policy analysis, rocsparse_solve_policy solve, void *temp_buffer)

rocsparse_status rocsparse_ccsrilu0_analysis(rocsparse_handle handle, rocsparse_int m, rocsparse_int nnz, const rocsparse_mat_descr descr, const rocsparse_float_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, rocsparse_analysis_policy analysis, rocsparse_solve_policy solve, void *temp_buffer)

rocsparse_status rocsparse_zcsrilu0_analysis(rocsparse_handle handle, rocsparse_int m, rocsparse_int nnz, const rocsparse_mat_descr descr, const rocsparse_double_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, rocsparse_analysis_policy analysis, rocsparse_solve_policy solve, void *temp_buffer)

  Incomplete LU factorization with 0 fill-ins and no pivoting using CSR storage format.

  `rocsparse_csrilu0_analysis` performs the analysis step for rocsparse_scsrilu0(), rocsparse_dcsrilu0(), rocsparse_ccsrilu0() and rocsparse_zcsrilu0(). It is expected that this function will be executed only once for a given matrix and particular operation type. The analysis meta data can be cleared by rocsparse_csrilu0_clear().

  `rocsparse_csrilu0_analysis` can share its meta data with rocsparse_scsric0_analysis(), rocsparse_dcsric0_analysis(), rocsparse_ccsric0_analysis(), rocsparse_zcsric0_analysis(), rocsparse_scsrsv_analysis(), rocsparse_dcsrsv_analysis(), rocsparse_ccsrsv_analysis(), rocsparse_zcsrsv_analysis(), rocsparse_scsrsm_analysis(), rocsparse_dcsrsm_analysis(), rocsparse_scsrsm_analysis() and rocsparse_dcsrsm_analysis(). Selecting rocsparse_analysis_policy_reuse policy can greatly improve computation performance of meta data. However, the user need to make sure that the sparsity pattern remains unchanged. If this cannot be assured, rocsparse_analysis_policy_force has to be used.

  Note

  If the matrix sparsity pattern changes, the gathered information will become invalid.

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows of the sparse CSR matrix.

    - nnz – [in] number of non-zero entries of the sparse CSR matrix.

    - descr – [in] descriptor of the sparse CSR matrix.

    - csr_val – [in] array of `nnz` elements of the sparse CSR matrix.

    - csr_row_ptr – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix.

    - csr_col_ind – [in] array of `nnz` elements containing the column indices of the sparse CSR matrix.

    - info – [out] structure that holds the information collected during the analysis step.

    - analysis – [in] rocsparse_analysis_policy_reuse or rocsparse_analysis_policy_force.

    - solve – [in] rocsparse_solve_policy_auto.

    - temp_buffer – [in] temporary storage buffer allocated by the user.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m` or `nnz` is invalid.

    - rocsparse_status_invalid_pointer – `descr`, `csr_val`, `csr_row_ptr`, `csr_col_ind`, `info` or `temp_buffer` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

    - rocsparse_status_not_implemented – `trans` != rocsparse_operation_none or rocsparse_matrix_type != rocsparse_matrix_type_general.

### rocsparse_csrilu0()

rocsparse_status rocsparse_scsrilu0(rocsparse_handle handle, rocsparse_int m, rocsparse_int nnz, const rocsparse_mat_descr descr, float *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, rocsparse_solve_policy policy, void *temp_buffer)

rocsparse_status rocsparse_dcsrilu0(rocsparse_handle handle, rocsparse_int m, rocsparse_int nnz, const rocsparse_mat_descr descr, double *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, rocsparse_solve_policy policy, void *temp_buffer)

rocsparse_status rocsparse_ccsrilu0(rocsparse_handle handle, rocsparse_int m, rocsparse_int nnz, const rocsparse_mat_descr descr, rocsparse_float_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, rocsparse_solve_policy policy, void *temp_buffer)

rocsparse_status rocsparse_zcsrilu0(rocsparse_handle handle, rocsparse_int m, rocsparse_int nnz, const rocsparse_mat_descr descr, rocsparse_double_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, rocsparse_solve_policy policy, void *temp_buffer)

  Incomplete LU factorization with 0 fill-ins and no pivoting using CSR storage format.

  `rocsparse_csrilu0` computes the incomplete LU factorization with 0 fill-ins and no pivoting of a sparse \(m \times m\) CSR matrix \(A\), such that

  \[ A \approx LU \]

  `rocsparse_csrilu0` requires a user allocated temporary buffer. Its size is returned by rocsparse_scsrilu0_buffer_size(), rocsparse_dcsrilu0_buffer_size(), rocsparse_ccsrilu0_buffer_size() or rocsparse_zcsrilu0_buffer_size(). Furthermore, analysis meta data is required. It can be obtained by rocsparse_scsrilu0_analysis(), rocsparse_dcsrilu0_analysis(), rocsparse_ccsrilu0_analysis() or rocsparse_zcsrilu0_analysis(). `rocsparse_csrilu0` reports the first zero pivot (either numerical or structural zero). The zero pivot status can be obtained by calling rocsparse_csrilu0_zero_pivot().

  Example

    Consider the sparse \(m \times m\) matrix \(A\), stored in CSR storage format. The following example computes the incomplete LU factorization \(M \approx LU\) and solves the preconditioned system \(My = x\).

        // Create rocSPARSE handle
        rocsparse_handle handle;
        rocsparse_create_handle(&handle);

        // Create matrix descriptor for M
        rocsparse_mat_descr descr_M;
        rocsparse_create_mat_descr(&descr_M);

        // Create matrix descriptor for L
        rocsparse_mat_descr descr_L;
        rocsparse_create_mat_descr(&descr_L);
        rocsparse_set_mat_fill_mode(descr_L, rocsparse_fill_mode_lower);
        rocsparse_set_mat_diag_type(descr_L, rocsparse_diag_type_unit);

        // Create matrix descriptor for U
        rocsparse_mat_descr descr_U;
        rocsparse_create_mat_descr(&descr_U);
        rocsparse_set_mat_fill_mode(descr_U, rocsparse_fill_mode_upper);
        rocsparse_set_mat_diag_type(descr_U, rocsparse_diag_type_non_unit);

        // Create matrix info structure
        rocsparse_mat_info info;
        rocsparse_create_mat_info(&info);

        // Obtain required buffer size
        size_t buffer_size_M;
        size_t buffer_size_L;
        size_t buffer_size_U;
        rocsparse_dcsrilu0_buffer_size(handle,
                                      m,
                                      nnz,
                                      descr_M,
                                      csr_val,
                                      csr_row_ptr,
                                      csr_col_ind,
                                      info,
                                      &buffer_size_M);
        rocsparse_dcsrsv_buffer_size(handle,
                                     rocsparse_operation_none,
                                     m,
                                     nnz,
                                     descr_L,
                                     csr_val,
                                     csr_row_ptr,
                                     csr_col_ind,
                                     info,
                                     &buffer_size_L);
        rocsparse_dcsrsv_buffer_size(handle,
                                     rocsparse_operation_none,
                                     m,
                                     nnz,
                                     descr_U,
                                     csr_val,
                                     csr_row_ptr,
                                     csr_col_ind,
                                     info,
                                     &buffer_size_U);

        size_t buffer_size = max(buffer_size_M, max(buffer_size_L, buffer_size_U));

        // Allocate temporary buffer
        void* temp_buffer;
        hipMalloc(&temp_buffer, buffer_size);

        // Perform analysis steps, using rocsparse_analysis_policy_reuse to improve
        // computation performance
        rocsparse_dcsrilu0_analysis(handle,
                                    m,
                                    nnz,
                                    descr_M,
                                    csr_val,
                                    csr_row_ptr,
                                    csr_col_ind,
                                    info,
                                    rocsparse_analysis_policy_reuse,
                                    rocsparse_solve_policy_auto,
                                    temp_buffer);
        rocsparse_dcsrsv_analysis(handle,
                                  rocsparse_operation_none,
                                  m,
                                  nnz,
                                  descr_L,
                                  csr_val,
                                  csr_row_ptr,
                                  csr_col_ind,
                                  info,
                                  rocsparse_analysis_policy_reuse,
                                  rocsparse_solve_policy_auto,
                                  temp_buffer);
        rocsparse_dcsrsv_analysis(handle,
                                  rocsparse_operation_none,
                                  m,
                                  nnz,
                                  descr_U,
                                  csr_val,
                                  csr_row_ptr,
                                  csr_col_ind,
                                  info,
                                  rocsparse_analysis_policy_reuse,
                                  rocsparse_solve_policy_auto,
                                  temp_buffer);

        // Check for zero pivot
        rocsparse_int position;
        if(rocsparse_status_zero_pivot == rocsparse_csrilu0_zero_pivot(handle,
                                                                       info,
                                                                       &position))
        {
            printf("A has structural zero at A(%d,%d)\n", position, position);
        }

        // Compute incomplete LU factorization
        rocsparse_dcsrilu0(handle,
                           m,
                           nnz,
                           descr_M,
                           csr_val,
                           csr_row_ptr,
                           csr_col_ind,
                           info,
                           rocsparse_solve_policy_auto,
                           temp_buffer);

        // Check for zero pivot
        if(rocsparse_status_zero_pivot == rocsparse_csrilu0_zero_pivot(handle,
                                                                       info,
                                                                       &position))
        {
            printf("U has structural and/or numerical zero at U(%d,%d)\n",
                   position,
                   position);
        }

        // Solve Lz = x
        rocsparse_dcsrsv_solve(handle,
                               rocsparse_operation_none,
                               m,
                               nnz,
                               &alpha,
                               descr_L,
                               csr_val,
                               csr_row_ptr,
                               csr_col_ind,
                               info,
                               x,
                               z,
                               rocsparse_solve_policy_auto,
                               temp_buffer);

        // Solve Uy = z
        rocsparse_dcsrsv_solve(handle,
                               rocsparse_operation_none,
                               m,
                               nnz,
                               &alpha,
                               descr_U,
                               csr_val,
                               csr_row_ptr,
                               csr_col_ind,
                               info,
                               z,
                               y,
                               rocsparse_solve_policy_auto,
                               temp_buffer);

        // Clean up
        hipFree(temp_buffer);
        rocsparse_destroy_mat_info(info);
        rocsparse_destroy_mat_descr(descr_M);
        rocsparse_destroy_mat_descr(descr_L);
        rocsparse_destroy_mat_descr(descr_U);
        rocsparse_destroy_handle(handle);

  Note

  The sparse CSR matrix has to be sorted. This can be achieved by calling rocsparse_csrsort().

  Note

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

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows of the sparse CSR matrix.

    - nnz – [in] number of non-zero entries of the sparse CSR matrix.

    - descr – [in] descriptor of the sparse CSR matrix.

    - csr_val – [inout] array of `nnz` elements of the sparse CSR matrix.

    - csr_row_ptr – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix.

    - csr_col_ind – [in] array of `nnz` elements containing the column indices of the sparse CSR matrix.

    - info – [in] structure that holds the information collected during the analysis step.

    - policy – [in] rocsparse_solve_policy_auto.

    - temp_buffer – [in] temporary storage buffer allocated by the user.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m` or `nnz` is invalid.

    - rocsparse_status_invalid_pointer – `descr`, `csr_val`, `csr_row_ptr` or `csr_col_ind` pointer is invalid.

    - rocsparse_status_arch_mismatch – the device is not supported.

    - rocsparse_status_internal_error – an internal error occurred.

    - rocsparse_status_not_implemented – `trans` != rocsparse_operation_none or rocsparse_matrix_type != rocsparse_matrix_type_general.

### rocsparse_csrilu0_clear()

rocsparse_status rocsparse_csrilu0_clear(rocsparse_handle handle, rocsparse_mat_info info)

  Incomplete LU factorization with 0 fill-ins and no pivoting using CSR storage format.

  `rocsparse_csrilu0_clear` deallocates all memory that was allocated by rocsparse_scsrilu0_analysis(), rocsparse_dcsrilu0_analysis(), rocsparse_ccsrilu0_analysis() or rocsparse_zcsrilu0_analysis(). This is especially useful, if memory is an issue and the analysis data is not required for further computation.

  Note

  Calling `rocsparse_csrilu0_clear` is optional. All allocated resources will be cleared, when the opaque rocsparse_mat_info struct is destroyed using rocsparse_destroy_mat_info().

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - info – [inout] structure that holds the information collected during the analysis step.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_pointer – `info` pointer is invalid.

    - rocsparse_status_memory_error – the buffer holding the meta data could not be deallocated.

    - rocsparse_status_internal_error – an internal error occurred.

### rocsparse_gtsv_buffer_size()

rocsparse_status rocsparse_sgtsv_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const float *dl, const float *d, const float *du, const float *B, rocsparse_int ldb, size_t *buffer_size)

rocsparse_status rocsparse_dgtsv_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const double *dl, const double *d, const double *du, const double *B, rocsparse_int ldb, size_t *buffer_size)

rocsparse_status rocsparse_cgtsv_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_float_complex *dl, const rocsparse_float_complex *d, const rocsparse_float_complex *du, const rocsparse_float_complex *B, rocsparse_int ldb, size_t *buffer_size)

rocsparse_status rocsparse_zgtsv_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_double_complex *dl, const rocsparse_double_complex *d, const rocsparse_double_complex *du, const rocsparse_double_complex *B, rocsparse_int ldb, size_t *buffer_size)

  Tridiagonal solver with pivoting.

  `rocsparse_gtsv_buffer_size` returns the size of the temporary storage buffer that is required by rocsparse_sgtsv(), rocsparse_dgtsv(), rocsparse_cgtsv() and rocsparse_zgtsv(). The temporary storage buffer must be allocated by the user.

  Note

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

  Note

  This routine supports execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] size of the tri-diagonal linear system (must be >= 2).

    - n – [in] number of columns in the dense matrix B.

    - dl – [in] lower diagonal of tri-diagonal system. First entry must be zero.

    - d – [in] main diagonal of tri-diagonal system.

    - du – [in] upper diagonal of tri-diagonal system. Last entry must be zero.

    - B – [in] Dense matrix of size ( `ldb`, `n` ).

    - ldb – [in] Leading dimension of B. Must satisfy `ldb` >= max(1, m).

    - buffer_size – [out] number of bytes of the temporary storage buffer required by rocsparse_sgtsv(), rocsparse_dgtsv(), rocsparse_cgtsv() and rocsparse_zgtsv().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m`, `n` or `ldb` is invalid.

    - rocsparse_status_invalid_pointer – `dl`, `d`, `du`, `B` or `buffer_size` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

### rocsparse_gtsv()

rocsparse_status rocsparse_sgtsv(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const float *dl, const float *d, const float *du, float *B, rocsparse_int ldb, void *temp_buffer)

rocsparse_status rocsparse_dgtsv(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const double *dl, const double *d, const double *du, double *B, rocsparse_int ldb, void *temp_buffer)

rocsparse_status rocsparse_cgtsv(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_float_complex *dl, const rocsparse_float_complex *d, const rocsparse_float_complex *du, rocsparse_float_complex *B, rocsparse_int ldb, void *temp_buffer)

rocsparse_status rocsparse_zgtsv(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_double_complex *dl, const rocsparse_double_complex *d, const rocsparse_double_complex *du, rocsparse_double_complex *B, rocsparse_int ldb, void *temp_buffer)

  Tridiagonal solver with pivoting.

  `rocsparse_gtsv` solves a tridiagonal system for multiple right hand sides using pivoting.

  Note

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

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] size of the tri-diagonal linear system (must be >= 2).

    - n – [in] number of columns in the dense matrix B.

    - dl – [in] lower diagonal of tri-diagonal system. First entry must be zero.

    - d – [in] main diagonal of tri-diagonal system.

    - du – [in] upper diagonal of tri-diagonal system. Last entry must be zero.

    - B – [inout] Dense matrix of size ( `ldb`, `n` ).

    - ldb – [in] Leading dimension of B. Must satisfy `ldb` >= max(1, m).

    - temp_buffer – [in] temporary storage buffer allocated by the user.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m`, `n` or `ldb` is invalid.

    - rocsparse_status_invalid_pointer – `dl`, `d`, `du`, `B` or `temp_buffer` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

### rocsparse_gtsv_no_pivot_buffer_size()

rocsparse_status rocsparse_sgtsv_no_pivot_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const float *dl, const float *d, const float *du, const float *B, rocsparse_int ldb, size_t *buffer_size)

rocsparse_status rocsparse_dgtsv_no_pivot_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const double *dl, const double *d, const double *du, const double *B, rocsparse_int ldb, size_t *buffer_size)

rocsparse_status rocsparse_cgtsv_no_pivot_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_float_complex *dl, const rocsparse_float_complex *d, const rocsparse_float_complex *du, const rocsparse_float_complex *B, rocsparse_int ldb, size_t *buffer_size)

rocsparse_status rocsparse_zgtsv_no_pivot_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_double_complex *dl, const rocsparse_double_complex *d, const rocsparse_double_complex *du, const rocsparse_double_complex *B, rocsparse_int ldb, size_t *buffer_size)

  Tridiagonal solver (no pivoting)

  `rocsparse_gtsv_no_pivot_buffer_size` returns the size of the temporary storage buffer that is required by rocsparse_sgtsv_no_pivot(), rocsparse_dgtsv_no_pivot(), rocsparse_cgtsv_no_pivot() and rocsparse_zgtsv_no_pivot(). The temporary storage buffer must be allocated by the user.

  Note

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

  Note

  This routine supports execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] size of the tri-diagonal linear system (must be >= 2).

    - n – [in] number of columns in the dense matrix B.

    - dl – [in] lower diagonal of tri-diagonal system. First entry must be zero.

    - d – [in] main diagonal of tri-diagonal system.

    - du – [in] upper diagonal of tri-diagonal system. Last entry must be zero.

    - B – [in] Dense matrix of size ( `ldb`, `n` ).

    - ldb – [in] Leading dimension of B. Must satisfy `ldb` >= max(1, m).

    - buffer_size – [out] number of bytes of the temporary storage buffer required by rocsparse_sgtsv_no_pivot(), rocsparse_dgtsv_no_pivot(), rocsparse_cgtsv_no_pivot() and rocsparse_zgtsv_no_pivot().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m`, `n` or `ldb` is invalid.

    - rocsparse_status_invalid_pointer – `dl`, `d`, `du`, `B` or `buffer_size` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

### rocsparse_gtsv_no_pivot()

rocsparse_status rocsparse_sgtsv_no_pivot(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const float *dl, const float *d, const float *du, float *B, rocsparse_int ldb, void *temp_buffer)

rocsparse_status rocsparse_dgtsv_no_pivot(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const double *dl, const double *d, const double *du, double *B, rocsparse_int ldb, void *temp_buffer)

rocsparse_status rocsparse_cgtsv_no_pivot(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_float_complex *dl, const rocsparse_float_complex *d, const rocsparse_float_complex *du, rocsparse_float_complex *B, rocsparse_int ldb, void *temp_buffer)

rocsparse_status rocsparse_zgtsv_no_pivot(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_double_complex *dl, const rocsparse_double_complex *d, const rocsparse_double_complex *du, rocsparse_double_complex *B, rocsparse_int ldb, void *temp_buffer)

  Tridiagonal solver (no pivoting)

  `rocsparse_gtsv_no_pivot` solves a tridiagonal linear system for multiple right-hand sides

  Note

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

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] size of the tri-diagonal linear system (must be >= 2).

    - n – [in] number of columns in the dense matrix B.

    - dl – [in] lower diagonal of tri-diagonal system. First entry must be zero.

    - d – [in] main diagonal of tri-diagonal system.

    - du – [in] upper diagonal of tri-diagonal system. Last entry must be zero.

    - B – [inout] Dense matrix of size ( `ldb`, `n` ).

    - ldb – [in] Leading dimension of B. Must satisfy `ldb` >= max(1, m).

    - temp_buffer – [in] temporary storage buffer allocated by the user.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m`, `n` or `ldb` is invalid.

    - rocsparse_status_invalid_pointer – `dl`, `d`, `du`, `B` or `temp_buffer` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

### rocsparse_gtsv_no_pivot_strided_batch_buffer_size()

rocsparse_status rocsparse_sgtsv_no_pivot_strided_batch_buffer_size(rocsparse_handle handle, rocsparse_int m, const float *dl, const float *d, const float *du, const float *x, rocsparse_int batch_count, rocsparse_int batch_stride, size_t *buffer_size)

rocsparse_status rocsparse_dgtsv_no_pivot_strided_batch_buffer_size(rocsparse_handle handle, rocsparse_int m, const double *dl, const double *d, const double *du, const double *x, rocsparse_int batch_count, rocsparse_int batch_stride, size_t *buffer_size)

rocsparse_status rocsparse_cgtsv_no_pivot_strided_batch_buffer_size(rocsparse_handle handle, rocsparse_int m, const rocsparse_float_complex *dl, const rocsparse_float_complex *d, const rocsparse_float_complex *du, const rocsparse_float_complex *x, rocsparse_int batch_count, rocsparse_int batch_stride, size_t *buffer_size)

rocsparse_status rocsparse_zgtsv_no_pivot_strided_batch_buffer_size(rocsparse_handle handle, rocsparse_int m, const rocsparse_double_complex *dl, const rocsparse_double_complex *d, const rocsparse_double_complex *du, const rocsparse_double_complex *x, rocsparse_int batch_count, rocsparse_int batch_stride, size_t *buffer_size)

  Strided Batch tridiagonal solver (no pivoting)

  `rocsparse_gtsv_no_pivot_strided_batch_buffer_size` returns the size of the temporary storage buffer that is required by rocsparse_sgtsv_no_pivot_strided_batch(), rocsparse_dgtsv_no_pivot_strided_batch(), rocsparse_cgtsv_no_pivot_strided_batch() and rocsparse_zgtsv_no_pivot_strided_batch(). The temporary storage buffer must be allocated by the user.

  Note

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

  Note

  This routine supports execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] size of the tri-diagonal linear system.

    - dl – [in] lower diagonal of tri-diagonal system where the ith system lower diagonal starts at `dl+batch_stride*i`.

    - d – [in] main diagonal of tri-diagonal system where the ith system diagonal starts at `d+batch_stride*i`.

    - du – [in] upper diagonal of tri-diagonal system where the ith system upper diagonal starts at `du+batch_stride*i`.

    - x – [inout] Dense array of righthand-sides where the ith righthand-side starts at `x+batch_stride*i`.

    - batch_count – [in] The number of systems to solve.

    - batch_stride – [in] The number of elements that separate each system. Must satisfy `batch_stride` >= m.

    - buffer_size – [out] number of bytes of the temporary storage buffer required by rocsparse_sgtsv_no_pivot_strided_batch(), rocsparse_dgtsv_no_pivot_strided_batch(), rocsparse_cgtsv_no_pivot_strided_batch() and rocsparse_zgtsv_no_pivot_strided_batch().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m`, `batch_count` or `batch_stride` is invalid.

    - rocsparse_status_invalid_pointer – `dl`, `d`, `du`, `x` or `buffer_size` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

### rocsparse_gtsv_no_pivot_strided_batch()

rocsparse_status rocsparse_sgtsv_no_pivot_strided_batch(rocsparse_handle handle, rocsparse_int m, const float *dl, const float *d, const float *du, float *x, rocsparse_int batch_count, rocsparse_int batch_stride, void *temp_buffer)

rocsparse_status rocsparse_dgtsv_no_pivot_strided_batch(rocsparse_handle handle, rocsparse_int m, const double *dl, const double *d, const double *du, double *x, rocsparse_int batch_count, rocsparse_int batch_stride, void *temp_buffer)

rocsparse_status rocsparse_cgtsv_no_pivot_strided_batch(rocsparse_handle handle, rocsparse_int m, const rocsparse_float_complex *dl, const rocsparse_float_complex *d, const rocsparse_float_complex *du, rocsparse_float_complex *x, rocsparse_int batch_count, rocsparse_int batch_stride, void *temp_buffer)

rocsparse_status rocsparse_zgtsv_no_pivot_strided_batch(rocsparse_handle handle, rocsparse_int m, const rocsparse_double_complex *dl, const rocsparse_double_complex *d, const rocsparse_double_complex *du, rocsparse_double_complex *x, rocsparse_int batch_count, rocsparse_int batch_stride, void *temp_buffer)

  Strided Batch tridiagonal solver (no pivoting)

  `rocsparse_gtsv_no_pivot_strided_batch` solves a batched tridiagonal linear system

  Note

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

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] size of the tri-diagonal linear system (must be >= 2).

    - dl – [in] lower diagonal of tri-diagonal system. First entry must be zero.

    - d – [in] main diagonal of tri-diagonal system.

    - du – [in] upper diagonal of tri-diagonal system. Last entry must be zero.

    - x – [inout] Dense array of righthand-sides where the ith righthand-side starts at `x+batch_stride*i`.

    - batch_count – [in] The number of systems to solve.

    - batch_stride – [in] The number of elements that separate each system. Must satisfy `batch_stride` >= m.

    - temp_buffer – [in] temporary storage buffer allocated by the user.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m`, `batch_count` or `batch_stride` is invalid.

    - rocsparse_status_invalid_pointer – `dl`, `d`, `du`, `x` or `temp_buffer` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

### rocsparse_gtsv_interleaved_batch_buffer_size()

rocsparse_status rocsparse_sgtsv_interleaved_batch_buffer_size(rocsparse_handle handle, rocsparse_gtsv_interleaved_alg alg, rocsparse_int m, const float *dl, const float *d, const float *du, const float *x, rocsparse_int batch_count, rocsparse_int batch_stride, size_t *buffer_size)

rocsparse_status rocsparse_dgtsv_interleaved_batch_buffer_size(rocsparse_handle handle, rocsparse_gtsv_interleaved_alg alg, rocsparse_int m, const double *dl, const double *d, const double *du, const double *x, rocsparse_int batch_count, rocsparse_int batch_stride, size_t *buffer_size)

rocsparse_status rocsparse_cgtsv_interleaved_batch_buffer_size(rocsparse_handle handle, rocsparse_gtsv_interleaved_alg alg, rocsparse_int m, const rocsparse_float_complex *dl, const rocsparse_float_complex *d, const rocsparse_float_complex *du, const rocsparse_float_complex *x, rocsparse_int batch_count, rocsparse_int batch_stride, size_t *buffer_size)

rocsparse_status rocsparse_zgtsv_interleaved_batch_buffer_size(rocsparse_handle handle, rocsparse_gtsv_interleaved_alg alg, rocsparse_int m, const rocsparse_double_complex *dl, const rocsparse_double_complex *d, const rocsparse_double_complex *du, const rocsparse_double_complex *x, rocsparse_int batch_count, rocsparse_int batch_stride, size_t *buffer_size)

  Interleaved Batch tridiagonal solver.

  `rocsparse_gtsv_interleaved_batch_buffer_size` returns the size of the temporary storage buffer that is required by rocsparse_sgtsv_interleaved_batch(), rocsparse_dgtsv_interleaved_batch(), rocsparse_cgtsv_interleaved_batch() and rocsparse_zgtsv_interleaved_batch(). The temporary storage buffer must be allocated by the user.

  Note

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

  Note

  This routine supports execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - alg – [in] Algorithm to use when solving tridiagonal systems. Options are thomas ( `rocsparse_gtsv_interleaved_thomas` ), LU ( `rocsparse_gtsv_interleaved_lu` ), or QR ( `rocsparse_gtsv_interleaved_qr` ). Passing `rocsparse_gtsv_interleaved_default` defaults the algorithm to use QR. Thomas algorithm is the fastest but is not stable while LU and QR are slower but are stable.

    - m – [in] size of the tri-diagonal linear system.

    - dl – [in] lower diagonal of tri-diagonal system. The first element of the lower diagonal must be zero.

    - d – [in] main diagonal of tri-diagonal system.

    - du – [in] upper diagonal of tri-diagonal system. The last element of the upper diagonal must be zero.

    - x – [inout] Dense array of righthand-sides with dimension `batch_stride` by `m`.

    - batch_count – [in] The number of systems to solve.

    - batch_stride – [in] The number of elements that separate consecutive elements in a system. Must satisfy `batch_stride` >= batch_count.

    - buffer_size – [out] number of bytes of the temporary storage buffer required by rocsparse_sgtsv_interleaved_batch(), rocsparse_dgtsv_interleaved_batch(), rocsparse_cgtsv_interleaved_batch() and rocsparse_zgtsv_interleaved_batch().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m`, `batch_count`, `batch_stride` is invalid.

    - rocsparse_status_invalid_pointer – `dl`, `d`, `du`, `x` or `buffer_size` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

### rocsparse_gtsv_interleaved_batch()

rocsparse_status rocsparse_sgtsv_interleaved_batch(rocsparse_handle handle, rocsparse_gtsv_interleaved_alg alg, rocsparse_int m, float *dl, float *d, float *du, float *x, rocsparse_int batch_count, rocsparse_int batch_stride, void *temp_buffer)

rocsparse_status rocsparse_dgtsv_interleaved_batch(rocsparse_handle handle, rocsparse_gtsv_interleaved_alg alg, rocsparse_int m, double *dl, double *d, double *du, double *x, rocsparse_int batch_count, rocsparse_int batch_stride, void *temp_buffer)

rocsparse_status rocsparse_cgtsv_interleaved_batch(rocsparse_handle handle, rocsparse_gtsv_interleaved_alg alg, rocsparse_int m, rocsparse_float_complex *dl, rocsparse_float_complex *d, rocsparse_float_complex *du, rocsparse_float_complex *x, rocsparse_int batch_count, rocsparse_int batch_stride, void *temp_buffer)

rocsparse_status rocsparse_zgtsv_interleaved_batch(rocsparse_handle handle, rocsparse_gtsv_interleaved_alg alg, rocsparse_int m, rocsparse_double_complex *dl, rocsparse_double_complex *d, rocsparse_double_complex *du, rocsparse_double_complex *x, rocsparse_int batch_count, rocsparse_int batch_stride, void *temp_buffer)

  Interleaved Batch tridiagonal solver.

  `rocsparse_gtsv_interleaved_batch` solves a batched tridiagonal linear system. The routine requires a temporary storage buffer that must be allocated by the user. The size of this buffer can be determined by first calling `rocsparse_gtsv_interleaved_batch_buffer_size`. The user can specify different algorithms for `rocsparse_gtsv_interleaved_batch` to use. Options are thomas ( `rocsparse_gtsv_interleaved_thomas` ), LU ( `rocsparse_gtsv_interleaved_lu` ), or QR ( `rocsparse_gtsv_interleaved_qr` ). Passing `rocsparse_gtsv_interleaved_default` defaults the algorithm to use QR.

  Note

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

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - alg – [in] Algorithm to use when solving tridiagonal systems. Options are thomas ( `rocsparse_gtsv_interleaved_thomas` ), LU ( `rocsparse_gtsv_interleaved_lu` ), or QR ( `rocsparse_gtsv_interleaved_qr` ). Passing `rocsparse_gtsv_interleaved_default` defaults the algorithm to use QR. Thomas algorithm is the fastest but is not stable while LU and QR are slower but are stable.

    - m – [in] size of the tri-diagonal linear system.

    - dl – [inout] lower diagonal of tri-diagonal system. The first element of the lower diagonal must be zero.

    - d – [inout] main diagonal of tri-diagonal system.

    - du – [inout] upper diagonal of tri-diagonal system. The last element of the upper diagonal must be zero.

    - x – [inout] Dense array of righthand-sides with dimension `batch_stride` by `m`.

    - batch_count – [in] The number of systems to solve.

    - batch_stride – [in] The number of elements that separate consecutive elements in a system. Must satisfy `batch_stride` >= batch_count.

    - temp_buffer – [in] temporary storage buffer allocated by the user.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m` or `batch_count` or `batch_stride` is invalid.

    - rocsparse_status_invalid_pointer – `dl`, `d`, `du`, `x` or `temp_buffer` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

### rocsparse_gpsv_interleaved_batch_buffer_size()

rocsparse_status rocsparse_sgpsv_interleaved_batch_buffer_size(rocsparse_handle handle, rocsparse_gpsv_interleaved_alg alg, rocsparse_int m, const float *ds, const float *dl, const float *d, const float *du, const float *dw, const float *x, rocsparse_int batch_count, rocsparse_int batch_stride, size_t *buffer_size)

rocsparse_status rocsparse_dgpsv_interleaved_batch_buffer_size(rocsparse_handle handle, rocsparse_gpsv_interleaved_alg alg, rocsparse_int m, const double *ds, const double *dl, const double *d, const double *du, const double *dw, const double *x, rocsparse_int batch_count, rocsparse_int batch_stride, size_t *buffer_size)

rocsparse_status rocsparse_cgpsv_interleaved_batch_buffer_size(rocsparse_handle handle, rocsparse_gpsv_interleaved_alg alg, rocsparse_int m, const rocsparse_float_complex *ds, const rocsparse_float_complex *dl, const rocsparse_float_complex *d, const rocsparse_float_complex *du, const rocsparse_float_complex *dw, const rocsparse_float_complex *x, rocsparse_int batch_count, rocsparse_int batch_stride, size_t *buffer_size)

rocsparse_status rocsparse_zgpsv_interleaved_batch_buffer_size(rocsparse_handle handle, rocsparse_gpsv_interleaved_alg alg, rocsparse_int m, const rocsparse_double_complex *ds, const rocsparse_double_complex *dl, const rocsparse_double_complex *d, const rocsparse_double_complex *du, const rocsparse_double_complex *dw, const rocsparse_double_complex *x, rocsparse_int batch_count, rocsparse_int batch_stride, size_t *buffer_size)

  Batched Pentadiagonal solver.

  `rocsparse_gpsv_interleaved_batch_buffer_size` calculates the required buffer size for rocsparse_gpsv_interleaved_batch(). It is the users responsibility to allocate this buffer.

  Note

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

  Note

  This routine supports execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - alg – [in] algorithm to solve the linear system.

    - m – [in] size of the pentadiagonal linear system.

    - ds – [in] lower diagonal (distance 2) of pentadiagonal system. First two entries must be zero.

    - dl – [in] lower diagonal of pentadiagonal system. First entry must be zero.

    - d – [in] main diagonal of pentadiagonal system.

    - du – [in] upper diagonal of pentadiagonal system. Last entry must be zero.

    - dw – [in] upper diagonal (distance 2) of pentadiagonal system. Last two entries must be zero.

    - x – [in] Dense array of right-hand-sides with dimension `batch_stride` by `m`.

    - batch_count – [in] The number of systems to solve.

    - batch_stride – [in] The number of elements that separate consecutive elements in a system. Must satisfy `batch_stride` >= batch_count.

    - buffer_size – [out] Number of bytes of the temporary storage buffer required.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m`, `alg`, `batch_count` or `batch_stride` is invalid.

    - rocsparse_status_invalid_pointer – `ds`, `dl`, `d`, `du`, `dw`, `x` or `temp_buffer` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

### rocsparse_gpsv_interleaved_batch()

rocsparse_status rocsparse_sgpsv_interleaved_batch(rocsparse_handle handle, rocsparse_gpsv_interleaved_alg alg, rocsparse_int m, float *ds, float *dl, float *d, float *du, float *dw, float *x, rocsparse_int batch_count, rocsparse_int batch_stride, void *temp_buffer)

rocsparse_status rocsparse_dgpsv_interleaved_batch(rocsparse_handle handle, rocsparse_gpsv_interleaved_alg alg, rocsparse_int m, double *ds, double *dl, double *d, double *du, double *dw, double *x, rocsparse_int batch_count, rocsparse_int batch_stride, void *temp_buffer)

rocsparse_status rocsparse_cgpsv_interleaved_batch(rocsparse_handle handle, rocsparse_gpsv_interleaved_alg alg, rocsparse_int m, rocsparse_float_complex *ds, rocsparse_float_complex *dl, rocsparse_float_complex *d, rocsparse_float_complex *du, rocsparse_float_complex *dw, rocsparse_float_complex *x, rocsparse_int batch_count, rocsparse_int batch_stride, void *temp_buffer)

rocsparse_status rocsparse_zgpsv_interleaved_batch(rocsparse_handle handle, rocsparse_gpsv_interleaved_alg alg, rocsparse_int m, rocsparse_double_complex *ds, rocsparse_double_complex *dl, rocsparse_double_complex *d, rocsparse_double_complex *du, rocsparse_double_complex *dw, rocsparse_double_complex *x, rocsparse_int batch_count, rocsparse_int batch_stride, void *temp_buffer)

  Batched Pentadiagonal solver.

  `rocsparse_gpsv_interleaved_batch` solves a batch of pentadiagonal linear systems. The coefficient matrix of each pentadiagonal linear system is defined by five vectors for the lower part (ds, dl), main diagonal (d) and upper part (du, dw).

  The function requires a temporary buffer. The size of the required buffer is returned by rocsparse_gpsv_interleaved_batch_buffer_size().

  Note

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

  Note

  The routine is numerically stable because it uses QR to solve the linear systems.

  Note

  m need to be at least 3, to be a valid pentadiagonal matrix.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - alg – [in] algorithm to solve the linear system.

    - m – [in] size of the pentadiagonal linear system.

    - ds – [inout] lower diagonal (distance 2) of pentadiagonal system. First two entries must be zero.

    - dl – [inout] lower diagonal of pentadiagonal system. First entry must be zero.

    - d – [inout] main diagonal of pentadiagonal system.

    - du – [inout] upper diagonal of pentadiagonal system. Last entry must be zero.

    - dw – [inout] upper diagonal (distance 2) of pentadiagonal system. Last two entries must be zero.

    - x – [inout] Dense array of right-hand-sides with dimension `batch_stride` by `m`.

    - batch_count – [in] The number of systems to solve.

    - batch_stride – [in] The number of elements that separate consecutive elements in a system. Must satisfy `batch_stride` >= batch_count.

    - temp_buffer – [in] Temporary storage buffer allocated by the user.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m`, `alg`, `batch_count` or `batch_stride` is invalid.

    - rocsparse_status_invalid_pointer – `ds`, `dl`, `d`, `du`, `dw`, `x` or `temp_buffer` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

## Sparse Conversion Functions

This module holds all sparse conversion routines.

The sparse conversion routines describe operations on a matrix in sparse format to obtain a matrix in a different sparse format.

### rocsparse_csr2coo()

rocsparse_status rocsparse_csr2coo(rocsparse_handle handle, const rocsparse_int *csr_row_ptr, rocsparse_int nnz, rocsparse_int m, rocsparse_int *coo_row_ind, rocsparse_index_base idx_base)

  Convert a sparse CSR matrix into a sparse COO matrix.

  `rocsparse_csr2coo` converts the CSR array containing the row offsets, that point to the start of every row, into a COO array of row indices.

  Example

    This example converts a CSR matrix into a COO matrix.

        //     1 2 0 3 0
        // A = 0 4 5 0 0
        //     6 0 0 7 8

        rocsparse_int m   = 3;
        rocsparse_int n   = 5;
        rocsparse_int nnz = 8;

        csr_row_ptr[m+1] = {0, 3, 5, 8};             // device memory
        csr_col_ind[nnz] = {0, 1, 3, 1, 2, 0, 3, 4}; // device memory
        csr_val[nnz]     = {1, 2, 3, 4, 5, 6, 7, 8}; // device memory

        // Allocate COO matrix arrays
        rocsparse_int* coo_row_ind;
        rocsparse_int* coo_col_ind;
        float* coo_val;

        hipMalloc((void**)&coo_row_ind, sizeof(rocsparse_int) * nnz);
        hipMalloc((void**)&coo_col_ind, sizeof(rocsparse_int) * nnz);
        hipMalloc((void**)&coo_val, sizeof(float) * nnz);

        // Convert the csr row offsets into coo row indices
        rocsparse_csr2coo(handle,
                          csr_row_ptr,
                          nnz,
                          m,
                          coo_row_ind,
                          rocsparse_index_base_zero);

        // Copy the column and value arrays
        hipMemcpy(coo_col_ind,
                  csr_col_ind,
                  sizeof(rocsparse_int) * nnz,
                  hipMemcpyDeviceToDevice);

        hipMemcpy(coo_val,
                  csr_val,
                  sizeof(float) * nnz,
                  hipMemcpyDeviceToDevice);

  Note

  It can also be used to convert a CSC array containing the column offsets into a COO array of column indices.

  Note

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

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - csr_row_ptr – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix.

    - nnz – [in] number of non-zero entries of the sparse CSR matrix.

    - m – [in] number of rows of the sparse CSR matrix.

    - coo_row_ind – [out] array of `nnz` elements containing the row indices of the sparse COO matrix.

    - idx_base – [in] rocsparse_index_base_zero or rocsparse_index_base_one.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m` or `nnz` is invalid.

    - rocsparse_status_invalid_pointer – `csr_row_ptr` or `coo_row_ind` pointer is invalid.

    - rocsparse_status_arch_mismatch – the device is not supported.

### rocsparse_coo2csr()

rocsparse_status rocsparse_coo2csr(rocsparse_handle handle, const rocsparse_int *coo_row_ind, rocsparse_int nnz, rocsparse_int m, rocsparse_int *csr_row_ptr, rocsparse_index_base idx_base)

  Convert a sparse COO matrix into a sparse CSR matrix.

  `rocsparse_coo2csr` converts the COO array containing the row indices into a CSR array of row offsets, that point to the start of every row. It is assumed that the COO row index array is sorted.

  Example

    This example converts a COO matrix into a CSR matrix.

        //     1 2 0 3 0
        // A = 0 4 5 0 0
        //     6 0 0 7 8

        rocsparse_int m   = 3;
        rocsparse_int n   = 5;
        rocsparse_int nnz = 8;

        coo_row_ind[nnz] = {0, 0, 0, 1, 1, 2, 2, 2}; // device memory
        coo_col_ind[nnz] = {0, 1, 3, 1, 2, 0, 3, 4}; // device memory
        coo_val[nnz]     = {1, 2, 3, 4, 5, 6, 7, 8}; // device memory

        // Allocate CSR matrix arrays
        rocsparse_int* csr_row_ptr;
        rocsparse_int* csr_col_ind;
        float* csr_val;

        hipMalloc((void**)&csr_row_ptr, sizeof(rocsparse_int) * (m + 1));
        hipMalloc((void**)&csr_col_ind, sizeof(rocsparse_int) * nnz);
        hipMalloc((void**)&csr_val, sizeof(float) * nnz);

        // Convert the coo row indices into csr row offsets
        rocsparse_coo2csr(handle,
                          coo_row_ind,
                          nnz,
                          m,
                          csr_row_ptr,
                          rocsparse_index_base_zero);

        // Copy the column and value arrays
        hipMemcpy(csr_col_ind,
                  coo_col_ind,
                  sizeof(rocsparse_int) * nnz,
                  hipMemcpyDeviceToDevice);

        hipMemcpy(csr_val,
                  coo_val,
                  sizeof(float) * nnz,
                  hipMemcpyDeviceToDevice);

  Note

  It can also be used, to convert a COO array containing the column indices into a CSC array of column offsets, that point to the start of every column. Then, it is assumed that the COO column index array is sorted, instead.

  Note

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

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - coo_row_ind – [in] array of `nnz` elements containing the row indices of the sparse COO matrix.

    - nnz – [in] number of non-zero entries of the sparse CSR matrix.

    - m – [in] number of rows of the sparse CSR matrix.

    - csr_row_ptr – [out] array of `m+1` elements that point to the start of every row of the sparse CSR matrix.

    - idx_base – [in] rocsparse_index_base_zero or rocsparse_index_base_one.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m` or `nnz` is invalid.

    - rocsparse_status_invalid_pointer – `coo_row_ind` or `csr_row_ptr` pointer is invalid.

### rocsparse_csr2csc_buffer_size()

rocsparse_status rocsparse_csr2csc_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_action copy_values, size_t *buffer_size)

  Convert a sparse CSR matrix into a sparse CSC matrix.

  `rocsparse_csr2csc_buffer_size` returns the size of the temporary storage buffer required by rocsparse_scsr2csc(), rocsparse_dcsr2csc(), rocsparse_ccsr2csc() and rocsparse_zcsr2csc(). The temporary storage buffer must be allocated by the user.

  Note

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

  Note

  This routine supports execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows of the sparse CSR matrix.

    - n – [in] number of columns of the sparse CSR matrix.

    - nnz – [in] number of non-zero entries of the sparse CSR matrix.

    - csr_row_ptr – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix.

    - csr_col_ind – [in] array of `nnz` elements containing the column indices of the sparse CSR matrix.

    - copy_values – [in] rocsparse_action_symbolic or rocsparse_action_numeric.

    - buffer_size – [out] number of bytes of the temporary storage buffer required by rocsparse_scsr2csc(), rocsparse_dcsr2csc(), rocsparse_ccsr2csc() and rocsparse_zcsr2csc().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m`, `n` or `nnz` is invalid.

    - rocsparse_status_invalid_pointer – `csr_row_ptr`, `csr_col_ind` or `buffer_size` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

### rocsparse_csr2csc()

rocsparse_status rocsparse_scsr2csc(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const float *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, float *csc_val, rocsparse_int *csc_row_ind, rocsparse_int *csc_col_ptr, rocsparse_action copy_values, rocsparse_index_base idx_base, void *temp_buffer)

rocsparse_status rocsparse_dcsr2csc(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const double *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, double *csc_val, rocsparse_int *csc_row_ind, rocsparse_int *csc_col_ptr, rocsparse_action copy_values, rocsparse_index_base idx_base, void *temp_buffer)

rocsparse_status rocsparse_ccsr2csc(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const rocsparse_float_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_float_complex *csc_val, rocsparse_int *csc_row_ind, rocsparse_int *csc_col_ptr, rocsparse_action copy_values, rocsparse_index_base idx_base, void *temp_buffer)

rocsparse_status rocsparse_zcsr2csc(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const rocsparse_double_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_double_complex *csc_val, rocsparse_int *csc_row_ind, rocsparse_int *csc_col_ptr, rocsparse_action copy_values, rocsparse_index_base idx_base, void *temp_buffer)

  Convert a sparse CSR matrix into a sparse CSC matrix.

  `rocsparse_csr2csc` converts a CSR matrix into a CSC matrix. `rocsparse_csr2csc` can also be used to convert a CSC matrix into a CSR matrix. `copy_values` decides whether `csc_val` is being filled during conversion (rocsparse_action_numeric) or not (rocsparse_action_symbolic).

  `rocsparse_csr2csc` requires extra temporary storage buffer that has to be allocated by the user. Storage buffer size can be determined by rocsparse_csr2csc_buffer_size().

  Example

    This example computes the transpose of a CSR matrix.

        //     1 2 0 3 0
        // A = 0 4 5 0 0
        //     6 0 0 7 8

        rocsparse_int m_A   = 3;
        rocsparse_int n_A   = 5;
        rocsparse_int nnz_A = 8;

        csr_row_ptr_A[m+1] = {0, 3, 5, 8};             // device memory
        csr_col_ind_A[nnz] = {0, 1, 3, 1, 2, 0, 3, 4}; // device memory
        csr_val_A[nnz]     = {1, 2, 3, 4, 5, 6, 7, 8}; // device memory

        // Allocate memory for transposed CSR matrix
        rocsparse_int m_T   = n_A;
        rocsparse_int n_T   = m_A;
        rocsparse_int nnz_T = nnz_A;

        rocsparse_int* csr_row_ptr_T;
        rocsparse_int* csr_col_ind_T;
        float* csr_val_T;

        hipMalloc((void**)&csr_row_ptr_T, sizeof(rocsparse_int) * (m_T + 1));
        hipMalloc((void**)&csr_col_ind_T, sizeof(rocsparse_int) * nnz_T);
        hipMalloc((void**)&csr_val_T, sizeof(float) * nnz_T);

        // Obtain the temporary buffer size
        size_t buffer_size;
        rocsparse_csr2csc_buffer_size(handle,
                                      m_A,
                                      n_A,
                                      nnz_A,
                                      csr_row_ptr_A,
                                      csr_col_ind_A,
                                      rocsparse_action_numeric,
                                      &buffer_size);

        // Allocate temporary buffer
        void* temp_buffer;
        hipMalloc(&temp_buffer, buffer_size);

        rocsparse_scsr2csc(handle,
                           m_A,
                           n_A,
                           nnz_A,
                           csr_val_A,
                           csr_row_ptr_A,
                           csr_col_ind_A,
                           csr_val_T,
                           csr_col_ind_T,
                           csr_row_ptr_T,
                           rocsparse_action_numeric,
                           rocsparse_index_base_zero,
                           temp_buffer);

  Note

  The resulting matrix can also be seen as the transpose of the input matrix.

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows of the sparse CSR matrix.

    - n – [in] number of columns of the sparse CSR matrix.

    - nnz – [in] number of non-zero entries of the sparse CSR matrix.

    - csr_val – [in] array of `nnz` elements of the sparse CSR matrix.

    - csr_row_ptr – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix.

    - csr_col_ind – [in] array of `nnz` elements containing the column indices of the sparse CSR matrix.

    - csc_val – [out] array of `nnz` elements of the sparse CSC matrix.

    - csc_row_ind – [out] array of `nnz` elements containing the row indices of the sparse CSC matrix.

    - csc_col_ptr – [out] array of `n+1` elements that point to the start of every column of the sparse CSC matrix.

    - copy_values – [in] rocsparse_action_symbolic or rocsparse_action_numeric.

    - idx_base – [in] rocsparse_index_base_zero or rocsparse_index_base_one.

    - temp_buffer – [in] temporary storage buffer allocated by the user, size is returned by rocsparse_csr2csc_buffer_size().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m`, `n` or `nnz` is invalid.

    - rocsparse_status_invalid_pointer – `csr_val`, `csr_row_ptr`, `csr_col_ind`, `csc_val`, `csc_row_ind`, `csc_col_ptr` or `temp_buffer` pointer is invalid.

    - rocsparse_status_arch_mismatch – the device is not supported.

    - rocsparse_status_internal_error – an internal error occurred.

### rocsparse_gebsr2gebsc_buffer_size()

rocsparse_status rocsparse_sgebsr2gebsc_buffer_size(rocsparse_handle handle, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const float *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, size_t *p_buffer_size)

rocsparse_status rocsparse_dgebsr2gebsc_buffer_size(rocsparse_handle handle, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const double *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, size_t *p_buffer_size)

rocsparse_status rocsparse_cgebsr2gebsc_buffer_size(rocsparse_handle handle, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const rocsparse_float_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, size_t *p_buffer_size)

rocsparse_status rocsparse_zgebsr2gebsc_buffer_size(rocsparse_handle handle, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const rocsparse_double_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, size_t *p_buffer_size)

  Convert a sparse GEneral BSR matrix into a sparse GEneral BSC matrix.

  `rocsparse_gebsr2gebsc_buffer_size` returns the size of the temporary storage buffer required by rocsparse_sgebsr2gebsc(), rocsparse_dgebsr2gebsc(), rocsparse_cgebsr2gebsc() and rocsparse_zgebsr2gebsc(). The temporary storage buffer must be allocated by the user.

  Note

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

  Note

  This routine supports execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - mb – [in] number of rows of the sparse GEneral BSR matrix.

    - nb – [in] number of columns of the sparse GEneral BSR matrix.

    - nnzb – [in] number of non-zero entries of the sparse GEneral BSR matrix.

    - bsr_val – [in] array of `nnzb*row_block_dim*col_block_dim` containing the values of the sparse GEneral BSR matrix.

    - bsr_row_ptr – [in] array of `mb+1` elements that point to the start of every row of the sparse GEneral BSR matrix.

    - bsr_col_ind – [in] array of `nnzb` elements containing the column indices of the sparse GEneral BSR matrix.

    - row_block_dim – [in] row size of the blocks in the sparse general BSR matrix.

    - col_block_dim – [in] col size of the blocks in the sparse general BSR matrix.

    - p_buffer_size – [out] number of bytes of the temporary storage buffer required by rocsparse_sgebsr2gebsc(), rocsparse_dgebsr2gebsc(), rocsparse_cgebsr2gebsc() and rocsparse_zgebsr2gebsc().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `mb`, `nb` or `nnzb` is invalid.

    - rocsparse_status_invalid_pointer – `bsr_row_ptr`, `bsr_col_ind` or `buffer_size` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

### rocsparse_gebsr2gebsc()

rocsparse_status rocsparse_sgebsr2gebsc(rocsparse_handle handle, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const float *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, float *bsc_val, rocsparse_int *bsc_row_ind, rocsparse_int *bsc_col_ptr, rocsparse_action copy_values, rocsparse_index_base idx_base, void *temp_buffer)

rocsparse_status rocsparse_dgebsr2gebsc(rocsparse_handle handle, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const double *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, double *bsc_val, rocsparse_int *bsc_row_ind, rocsparse_int *bsc_col_ptr, rocsparse_action copy_values, rocsparse_index_base idx_base, void *temp_buffer)

rocsparse_status rocsparse_cgebsr2gebsc(rocsparse_handle handle, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const rocsparse_float_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, rocsparse_float_complex *bsc_val, rocsparse_int *bsc_row_ind, rocsparse_int *bsc_col_ptr, rocsparse_action copy_values, rocsparse_index_base idx_base, void *temp_buffer)

rocsparse_status rocsparse_zgebsr2gebsc(rocsparse_handle handle, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const rocsparse_double_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, rocsparse_double_complex *bsc_val, rocsparse_int *bsc_row_ind, rocsparse_int *bsc_col_ptr, rocsparse_action copy_values, rocsparse_index_base idx_base, void *temp_buffer)

  Convert a sparse GEneral BSR matrix into a sparse GEneral BSC matrix.

  `rocsparse_gebsr2gebsc` converts a GEneral BSR matrix into a GEneral BSC matrix. `rocsparse_gebsr2gebsc` can also be used to convert a GEneral BSC matrix into a GEneral BSR matrix. `copy_values` decides whether `bsc_val` is being filled during conversion (rocsparse_action_numeric) or not (rocsparse_action_symbolic).

  `rocsparse_gebsr2gebsc` requires extra temporary storage buffer that has to be allocated by the user. Storage buffer size can be determined by rocsparse_gebsr2gebsc_buffer_size().

  Example

    This example computes the transpose of a GEneral BSR matrix.

        //     1 2 0 3
        // A = 0 4 5 0
        //     6 0 0 7
        //     1 2 3 4

        rocsparse_int mb_A   = 2;
        rocsparse_int row_block_dim = 2;
        rocsparse_int col_block_dim = 2;
        rocsparse_int nb_A   = 2;
        rocsparse_int nnzb_A = 4;

        bsr_row_ptr_A[mb_A+1] = {0, 2, 4};               // device memory
        bsr_col_ind_A[nnzb_A] = {0, 1, 0, 1}; // device memory
        bsr_val_A[nnzb_A]     = {1, 0, 2, 4, 0, 5, 3, 0, 6, 1, 0, 2, 0, 3, 7, 4}; // device memory

        // Allocate memory for transposed BSR matrix
        rocsparse_int mb_T   = nb_A;
        rocsparse_int nb_T   = mb_A;
        rocsparse_int nnzb_T = nnzb_A;

        rocsparse_int* bsr_row_ptr_T;
        rocsparse_int* bsr_col_ind_T;
        float* bsr_val_T;

        hipMalloc((void**)&bsr_row_ptr_T, sizeof(rocsparse_int) * (mb_T + 1));
        hipMalloc((void**)&bsr_col_ind_T, sizeof(rocsparse_int) * nnzb_T);
        hipMalloc((void**)&bsr_val_T, sizeof(float) * nnzb_T);

        // Obtain the temporary buffer size
        size_t buffer_size;
        rocsparse_gebsr2gebsc_buffer_size(handle,
                                      mb_A,
                                      nb_A,
                                      nnzb_A,
                                      bsr_row_ptr_A,
                                      bsr_col_ind_A,
                                      rocsparse_action_numeric,
                                      &buffer_size);

        // Allocate temporary buffer
        void* temp_buffer;
        hipMalloc(&temp_buffer, buffer_size);

        rocsparse_sgebsr2gebsc(handle,
                           mb_A,
                           nb_A,
                           nnzb_A,
                           bsr_val_A,
                           bsr_row_ptr_A,
                           bsr_col_ind_A,
                           row_block_dim,
                           col_block_dim,
                           bsr_val_T,
                           bsr_col_ind_T,
                           bsr_row_ptr_T,
                           rocsparse_action_numeric,
                           rocsparse_index_base_zero,
                           temp_buffer);

  Note

  The resulting matrix can also be seen as the transpose of the input matrix.

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - mb – [in] number of rows of the sparse GEneral BSR matrix.

    - nb – [in] number of columns of the sparse GEneral BSR matrix.

    - nnzb – [in] number of non-zero entries of the sparse GEneral BSR matrix.

    - bsr_val – [in] array of `nnzb` * `row_block_dim` * `col_block_dim` elements of the sparse GEneral BSR matrix.

    - bsr_row_ptr – [in] array of `m+1` elements that point to the start of every row of the sparse GEneral BSR matrix.

    - bsr_col_ind – [in] array of `nnz` elements containing the column indices of the sparse GEneral BSR matrix.

    - row_block_dim – [in] row size of the blocks in the sparse general BSR matrix.

    - col_block_dim – [in] col size of the blocks in the sparse general BSR matrix.

    - bsc_val – [out] array of `nnz` elements of the sparse BSC matrix.

    - bsc_row_ind – [out] array of `nnz` elements containing the row indices of the sparse BSC matrix.

    - bsc_col_ptr – [out] array of `n+1` elements that point to the start of every column of the sparse BSC matrix.

    - copy_values – [in] rocsparse_action_symbolic or rocsparse_action_numeric.

    - idx_base – [in] rocsparse_index_base_zero or rocsparse_index_base_one.

    - temp_buffer – [in] temporary storage buffer allocated by the user, size is returned by rocsparse_gebsr2gebsc_buffer_size().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `mb`, `nb` or `nnzb` is invalid.

    - rocsparse_status_invalid_pointer – `bsr_val`, `bsr_row_ptr`, `bsr_col_ind`, `bsc_val`, `bsc_row_ind`, `bsc_col_ptr` or `temp_buffer` pointer is invalid.

    - rocsparse_status_arch_mismatch – the device is not supported.

    - rocsparse_status_internal_error – an internal error occurred.

### rocsparse_csr2ell_width()

rocsparse_status rocsparse_csr2ell_width(rocsparse_handle handle, rocsparse_int m, const rocsparse_mat_descr csr_descr, const rocsparse_int *csr_row_ptr, const rocsparse_mat_descr ell_descr, rocsparse_int *ell_width)

  Convert a sparse CSR matrix into a sparse ELL matrix.

  `rocsparse_csr2ell_width` computes the maximum of the per row non-zero elements over all rows, the ELL `width`, for a given CSR matrix.

  Note

  This function is blocking with respect to the host.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows of the sparse CSR matrix.

    - csr_descr – [in] descriptor of the sparse CSR matrix. Currently, only rocsparse_matrix_type_general is supported.

    - csr_row_ptr – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix.

    - ell_descr – [in] descriptor of the sparse ELL matrix. Currently, only rocsparse_matrix_type_general is supported.

    - ell_width – [out] pointer to the number of non-zero elements per row in ELL storage format.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m` is invalid.

    - rocsparse_status_invalid_pointer – `csr_descr`, `csr_row_ptr`, or `ell_width` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

    - rocsparse_status_not_implemented – rocsparse_matrix_type != rocsparse_matrix_type_general.

### rocsparse_csr2ell()

rocsparse_status rocsparse_scsr2ell(rocsparse_handle handle, rocsparse_int m, const rocsparse_mat_descr csr_descr, const float *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, const rocsparse_mat_descr ell_descr, rocsparse_int ell_width, float *ell_val, rocsparse_int *ell_col_ind)

rocsparse_status rocsparse_dcsr2ell(rocsparse_handle handle, rocsparse_int m, const rocsparse_mat_descr csr_descr, const double *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, const rocsparse_mat_descr ell_descr, rocsparse_int ell_width, double *ell_val, rocsparse_int *ell_col_ind)

rocsparse_status rocsparse_ccsr2ell(rocsparse_handle handle, rocsparse_int m, const rocsparse_mat_descr csr_descr, const rocsparse_float_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, const rocsparse_mat_descr ell_descr, rocsparse_int ell_width, rocsparse_float_complex *ell_val, rocsparse_int *ell_col_ind)

rocsparse_status rocsparse_zcsr2ell(rocsparse_handle handle, rocsparse_int m, const rocsparse_mat_descr csr_descr, const rocsparse_double_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, const rocsparse_mat_descr ell_descr, rocsparse_int ell_width, rocsparse_double_complex *ell_val, rocsparse_int *ell_col_ind)

  Convert a sparse CSR matrix into a sparse ELL matrix.

  `rocsparse_csr2ell` converts a CSR matrix into an ELL matrix. It is assumed, that `ell_val` and `ell_col_ind` are allocated. Allocation size is computed by the number of rows times the number of ELL non-zero elements per row, such that \(\text{nnz}_{\text{ELL}} = m \cdot \text{ell_width}\). The number of ELL non-zero elements per row is obtained by rocsparse_csr2ell_width().

  Example

    This example converts a CSR matrix into an ELL matrix.

        //     1 2 0 3 0
        // A = 0 4 5 0 0
        //     6 0 0 7 8

        rocsparse_int m   = 3;
        rocsparse_int n   = 5;
        rocsparse_int nnz = 8;

        csr_row_ptr[m+1] = {0, 3, 5, 8};             // device memory
        csr_col_ind[nnz] = {0, 1, 3, 1, 2, 0, 3, 4}; // device memory
        csr_val[nnz]     = {1, 2, 3, 4, 5, 6, 7, 8}; // device memory

        // Create ELL matrix descriptor
        rocsparse_mat_descr ell_descr;
        rocsparse_create_mat_descr(&ell_descr);

        // Obtain the ELL width
        rocsparse_int ell_width;
        rocsparse_csr2ell_width(handle,
                                m,
                                csr_descr,
                                csr_row_ptr,
                                ell_descr,
                                &ell_width);

        // Compute ELL non-zero entries
        rocsparse_int ell_nnz = m * ell_width;

        // Allocate ELL column and value arrays
        rocsparse_int* ell_col_ind;
        hipMalloc((void**)&ell_col_ind, sizeof(rocsparse_int) * ell_nnz);

        float* ell_val;
        hipMalloc((void**)&ell_val, sizeof(float) * ell_nnz);

        // Format conversion
        rocsparse_scsr2ell(handle,
                           m,
                           csr_descr,
                           csr_val,
                           csr_row_ptr,
                           csr_col_ind,
                           ell_descr,
                           ell_width,
                           ell_val,
                           ell_col_ind);

  Note

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

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows of the sparse CSR matrix.

    - csr_descr – [in] descriptor of the sparse CSR matrix. Currently, only rocsparse_matrix_type_general is supported.

    - csr_val – [in] array containing the values of the sparse CSR matrix.

    - csr_row_ptr – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix.

    - csr_col_ind – [in] array containing the column indices of the sparse CSR matrix.

    - ell_descr – [in] descriptor of the sparse ELL matrix. Currently, only rocsparse_matrix_type_general is supported.

    - ell_width – [in] number of non-zero elements per row in ELL storage format.

    - ell_val – [out] array of `m` times `ell_width` elements of the sparse ELL matrix.

    - ell_col_ind – [out] array of `m` times `ell_width` elements containing the column indices of the sparse ELL matrix.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m` or `ell_width` is invalid.

    - rocsparse_status_invalid_pointer – `csr_descr`, `csr_val`, `csr_row_ptr`, `csr_col_ind`, `ell_descr`, `ell_val` or `ell_col_ind` pointer is invalid.

    - rocsparse_status_not_implemented – rocsparse_matrix_type != rocsparse_matrix_type_general.

### rocsparse_ell2csr_nnz()

rocsparse_status rocsparse_ell2csr_nnz(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr ell_descr, rocsparse_int ell_width, const rocsparse_int *ell_col_ind, const rocsparse_mat_descr csr_descr, rocsparse_int *csr_row_ptr, rocsparse_int *csr_nnz)

  Convert a sparse ELL matrix into a sparse CSR matrix.

  `rocsparse_ell2csr_nnz` computes the total CSR non-zero elements and the CSR row offsets, that point to the start of every row of the sparse CSR matrix, for a given ELL matrix. It is assumed that `csr_row_ptr` has been allocated with size `m+1`.

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows of the sparse ELL matrix.

    - n – [in] number of columns of the sparse ELL matrix.

    - ell_descr – [in] descriptor of the sparse ELL matrix. Currently, only rocsparse_matrix_type_general is supported.

    - ell_width – [in] number of non-zero elements per row in ELL storage format.

    - ell_col_ind – [in] array of `m` times `ell_width` elements containing the column indices of the sparse ELL matrix.

    - csr_descr – [in] descriptor of the sparse CSR matrix. Currently, only rocsparse_matrix_type_general is supported.

    - csr_row_ptr – [out] array of `m+1` elements that point to the start of every row of the sparse CSR matrix.

    - csr_nnz – [out] pointer to the total number of non-zero elements in CSR storage format.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m`, `n` or `ell_width` is invalid.

    - rocsparse_status_invalid_pointer – `ell_descr`, `ell_col_ind`, `csr_descr`, `csr_row_ptr` or `csr_nnz` pointer is invalid.

    - rocsparse_status_not_implemented – rocsparse_matrix_type != rocsparse_matrix_type_general.

### rocsparse_ell2csr()

rocsparse_status rocsparse_sell2csr(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr ell_descr, rocsparse_int ell_width, const float *ell_val, const rocsparse_int *ell_col_ind, const rocsparse_mat_descr csr_descr, float *csr_val, const rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind)

rocsparse_status rocsparse_dell2csr(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr ell_descr, rocsparse_int ell_width, const double *ell_val, const rocsparse_int *ell_col_ind, const rocsparse_mat_descr csr_descr, double *csr_val, const rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind)

rocsparse_status rocsparse_cell2csr(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr ell_descr, rocsparse_int ell_width, const rocsparse_float_complex *ell_val, const rocsparse_int *ell_col_ind, const rocsparse_mat_descr csr_descr, rocsparse_float_complex *csr_val, const rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind)

rocsparse_status rocsparse_zell2csr(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr ell_descr, rocsparse_int ell_width, const rocsparse_double_complex *ell_val, const rocsparse_int *ell_col_ind, const rocsparse_mat_descr csr_descr, rocsparse_double_complex *csr_val, const rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind)

  Convert a sparse ELL matrix into a sparse CSR matrix.

  `rocsparse_ell2csr` converts an ELL matrix into a CSR matrix. It is assumed that `csr_row_ptr` has already been filled and that `csr_val` and `csr_col_ind` are allocated by the user. `csr_row_ptr` and allocation size of `csr_col_ind` and `csr_val` is defined by the number of CSR non-zero elements. Both can be obtained by rocsparse_ell2csr_nnz().

  Example

    This example converts an ELL matrix into a CSR matrix.

        //     1 2 0 3 0
        // A = 0 4 5 0 0
        //     6 0 0 7 8

        rocsparse_int m         = 3;
        rocsparse_int n         = 5;
        rocsparse_int nnz       = 9;
        rocsparse_int ell_width = 3;

        ell_col_ind[nnz] = {0, 1, 0, 1, 2, 3, 3, -1, 4}; // device memory
        ell_val[nnz]     = {1, 4, 6, 2, 5, 7, 3, 0, 8};  // device memory

        // Create CSR matrix descriptor
        rocsparse_mat_descr csr_descr;
        rocsparse_create_mat_descr(&csr_descr);

        // Allocate csr_row_ptr array for row offsets
        rocsparse_int* csr_row_ptr;
        hipMalloc((void**)&csr_row_ptr, sizeof(rocsparse_int) * (m + 1));

        // Obtain the number of CSR non-zero entries
        // and fill csr_row_ptr array with row offsets
        rocsparse_int csr_nnz;
        rocsparse_ell2csr_nnz(handle,
                              m,
                              n,
                              ell_descr,
                              ell_width,
                              ell_col_ind,
                              csr_descr,
                              csr_row_ptr,
                              &csr_nnz);

        // Allocate CSR column and value arrays
        rocsparse_int* csr_col_ind;
        hipMalloc((void**)&csr_col_ind, sizeof(rocsparse_int) * csr_nnz);

        float* csr_val;
        hipMalloc((void**)&csr_val, sizeof(float) * csr_nnz);

        // Format conversion
        rocsparse_sell2csr(handle,
                           m,
                           n,
                           ell_descr,
                           ell_width,
                           ell_val,
                           ell_col_ind,
                           csr_descr,
                           csr_val,
                           csr_row_ptr,
                           csr_col_ind);

  Note

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

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows of the sparse ELL matrix.

    - n – [in] number of columns of the sparse ELL matrix.

    - ell_descr – [in] descriptor of the sparse ELL matrix. Currently, only rocsparse_matrix_type_general is supported.

    - ell_width – [in] number of non-zero elements per row in ELL storage format.

    - ell_val – [in] array of `m` times `ell_width` elements of the sparse ELL matrix.

    - ell_col_ind – [in] array of `m` times `ell_width` elements containing the column indices of the sparse ELL matrix.

    - csr_descr – [in] descriptor of the sparse CSR matrix. Currently, only rocsparse_matrix_type_general is supported.

    - csr_val – [out] array containing the values of the sparse CSR matrix.

    - csr_row_ptr – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix.

    - csr_col_ind – [out] array containing the column indices of the sparse CSR matrix.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m`, `n` or `ell_width` is invalid.

    - rocsparse_status_invalid_pointer – `csr_descr`, `csr_val`, `csr_row_ptr`, `csr_col_ind`, `ell_descr`, `ell_val` or `ell_col_ind` pointer is invalid.

    - rocsparse_status_not_implemented – rocsparse_matrix_type != rocsparse_matrix_type_general.

### rocsparse_csr2hyb()

rocsparse_status rocsparse_scsr2hyb(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const float *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_hyb_mat hyb, rocsparse_int user_ell_width, rocsparse_hyb_partition partition_type)

rocsparse_status rocsparse_dcsr2hyb(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const double *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_hyb_mat hyb, rocsparse_int user_ell_width, rocsparse_hyb_partition partition_type)

rocsparse_status rocsparse_ccsr2hyb(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const rocsparse_float_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_hyb_mat hyb, rocsparse_int user_ell_width, rocsparse_hyb_partition partition_type)

rocsparse_status rocsparse_zcsr2hyb(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const rocsparse_double_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_hyb_mat hyb, rocsparse_int user_ell_width, rocsparse_hyb_partition partition_type)

  Convert a sparse CSR matrix into a sparse HYB matrix.

  `rocsparse_csr2hyb` converts a CSR matrix into a HYB matrix. It is assumed that `hyb` has been initialized with rocsparse_create_hyb_mat().

  Example

    This example converts a CSR matrix into a HYB matrix using user defined partitioning.

        // Create HYB matrix structure
        rocsparse_hyb_mat hyb;
        rocsparse_create_hyb_mat(&hyb);

        // User defined ell width
        rocsparse_int user_ell_width = 5;

        // Perform the conversion
        rocsparse_scsr2hyb(handle,
                           m,
                           n,
                           descr,
                           csr_val,
                           csr_row_ptr,
                           csr_col_ind,
                           hyb,
                           user_ell_width,
                           rocsparse_hyb_partition_user);

        // Do some work

        // Clean up
        rocsparse_destroy_hyb_mat(hyb);

  Note

  This function requires a significant amount of storage for the HYB matrix, depending on the matrix structure.

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows of the sparse CSR matrix.

    - n – [in] number of columns of the sparse CSR matrix.

    - descr – [in] descriptor of the sparse CSR matrix. Currently, only rocsparse_matrix_type_general is supported.

    - csr_val – [in] array containing the values of the sparse CSR matrix.

    - csr_row_ptr – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix.

    - csr_col_ind – [in] array containing the column indices of the sparse CSR matrix.

    - hyb – [out] sparse matrix in HYB format.

    - user_ell_width – [in] width of the ELL part of the HYB matrix (only required if `partition_type` == rocsparse_hyb_partition_user).

    - partition_type – [in] rocsparse_hyb_partition_auto (recommended), rocsparse_hyb_partition_user or rocsparse_hyb_partition_max.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m`, `n` or `user_ell_width` is invalid.

    - rocsparse_status_invalid_value – `partition_type` is invalid.

    - rocsparse_status_invalid_pointer – `descr`, `hyb`, `csr_val`, `csr_row_ptr` or `csr_col_ind` pointer is invalid.

    - rocsparse_status_memory_error – the buffer for the HYB matrix could not be allocated.

    - rocsparse_status_internal_error – an internal error occurred.

    - rocsparse_status_not_implemented – rocsparse_matrix_type != rocsparse_matrix_type_general.

### rocsparse_hyb2csr_buffer_size()

rocsparse_status rocsparse_hyb2csr_buffer_size(rocsparse_handle handle, const rocsparse_mat_descr descr, const rocsparse_hyb_mat hyb, const rocsparse_int *csr_row_ptr, size_t *buffer_size)

  Convert a sparse HYB matrix into a sparse CSR matrix.

  `rocsparse_hyb2csr_buffer_size` returns the size of the temporary storage buffer required by rocsparse_shyb2csr(), rocsparse_dhyb2csr(), rocsparse_chyb2csr() and rocsparse_dhyb2csr(). The temporary storage buffer must be allocated by the user.

  Note

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

  Note

  This routine supports execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - descr – [in] descriptor of the sparse HYB matrix. Currently, only rocsparse_matrix_type_general is supported.

    - hyb – [in] sparse matrix in HYB format.

    - csr_row_ptr – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix.

    - buffer_size – [out] number of bytes of the temporary storage buffer required by rocsparse_shyb2csr(), rocsparse_dhyb2csr(), rocsparse_chyb2csr() and rocsparse_zhyb2csr().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_pointer – `descr`, `hyb`, `csr_row_ptr` or `buffer_size` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

    - rocsparse_status_not_implemented – rocsparse_matrix_type != rocsparse_matrix_type_general.

### rocsparse_hyb2csr()

rocsparse_status rocsparse_shyb2csr(rocsparse_handle handle, const rocsparse_mat_descr descr, const rocsparse_hyb_mat hyb, float *csr_val, rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind, void *temp_buffer)

rocsparse_status rocsparse_dhyb2csr(rocsparse_handle handle, const rocsparse_mat_descr descr, const rocsparse_hyb_mat hyb, double *csr_val, rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind, void *temp_buffer)

rocsparse_status rocsparse_chyb2csr(rocsparse_handle handle, const rocsparse_mat_descr descr, const rocsparse_hyb_mat hyb, rocsparse_float_complex *csr_val, rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind, void *temp_buffer)

rocsparse_status rocsparse_zhyb2csr(rocsparse_handle handle, const rocsparse_mat_descr descr, const rocsparse_hyb_mat hyb, rocsparse_double_complex *csr_val, rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind, void *temp_buffer)

  Convert a sparse HYB matrix into a sparse CSR matrix.

  `rocsparse_hyb2csr` converts a HYB matrix into a CSR matrix.

  `rocsparse_hyb2csr` requires extra temporary storage buffer that has to be allocated by the user. Storage buffer size can be determined by rocsparse_hyb2csr_buffer_size().

  Example

    This example converts a HYB matrix into a CSR matrix.

        // Create CSR matrix arrays
        rocsparse_int* csr_row_ptr;
        rocsparse_int* csr_col_ind;
        float* csr_val;

        hipMalloc((void**)&csr_row_ptr, sizeof(rocsparse_int) * (m + 1));
        hipMalloc((void**)&csr_col_ind, sizeof(rocsparse_int) * nnz);
        hipMalloc((void**)&csr_val, sizeof(float) * nnz);

        // Get required size of temporary buffer
        size_t size;
        rocsparse_hyb2csr_buffer_size(handle,
                                      descr,
                                      hyb,
                                      csr_row_ptr,
                                      &size);

        // Allocate temporary buffer
        void* buffer;
        hipMalloc(&buffer, size);

        // Perform the conversion
        rocsparse_shyb2csr(handle,
                           descr,
                           hyb,
                           csr_val,
                           csr_row_ptr,
                           csr_col_ind,
                           buffer);

  Note

  This function is blocking with respect to the host.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - descr – [in] descriptor of the sparse HYB matrix. Currently, only rocsparse_matrix_type_general is supported.

    - hyb – [in] sparse matrix in HYB format.

    - csr_val – [out] array containing the values of the sparse CSR matrix.

    - csr_row_ptr – [out] array of `m+1` elements that point to the start of every row of the sparse CSR matrix.

    - csr_col_ind – [out] array containing the column indices of the sparse CSR matrix.

    - temp_buffer – [in] temporary storage buffer allocated by the user, size is returned by rocsparse_hyb2csr_buffer_size().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_pointer – `descr`, `hyb`, `csr_val`, `csr_row_ptr`, `csr_col_ind` or `temp_buffer` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

    - rocsparse_status_not_implemented – rocsparse_matrix_type != rocsparse_matrix_type_general.

### rocsparse_bsr2csr()

rocsparse_status rocsparse_sbsr2csr(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, const rocsparse_mat_descr bsr_descr, const float *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, const rocsparse_mat_descr csr_descr, float *csr_val, rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind)

rocsparse_status rocsparse_dbsr2csr(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, const rocsparse_mat_descr bsr_descr, const double *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, const rocsparse_mat_descr csr_descr, double *csr_val, rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind)

rocsparse_status rocsparse_cbsr2csr(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, const rocsparse_mat_descr bsr_descr, const rocsparse_float_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, const rocsparse_mat_descr csr_descr, rocsparse_float_complex *csr_val, rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind)

rocsparse_status rocsparse_zbsr2csr(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, const rocsparse_mat_descr bsr_descr, const rocsparse_double_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, const rocsparse_mat_descr csr_descr, rocsparse_double_complex *csr_val, rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind)

  Convert a sparse BSR matrix into a sparse CSR matrix.

  `rocsparse_bsr2csr` converts a BSR matrix into a CSR matrix. It is assumed, that `csr_val`, `csr_col_ind` and `csr_row_ptr` are allocated. Allocation size for `csr_row_ptr` is computed by the number of block rows multiplied by the block dimension plus one. Allocation for `csr_val` and `csr_col_ind` is computed by the the number of blocks in the BSR matrix multiplied by the block dimension squared.

  Example

    This example converts a BSR matrix into an CSR matrix.

        //     1 4 0 0 0 0
        // A = 0 2 3 0 0 0
        //     5 0 0 7 8 0
        //     0 0 9 0 6 0

        rocsparse_int mb   = 2;
        rocsparse_int nb   = 3;
        rocsparse_int block_dim = 2;
        rocsparse_int m = Mb * block_dim;
        rocsparse_int n = Nb * block_dim;

        bsr_row_ptr[mb+1]                 = {0, 2, 5};                                                    // device memory
        bsr_col_ind[nnzb]                 = {0, 1, 0, 1, 2};                                              // device memory
        bsr_val[nnzb*block_dim*block_dim] = {1, 0, 4, 2, 0, 3, 0, 0, 5, 0, 0, 0, 0, 9, 7, 0, 8, 6, 0, 0}; // device memory

        rocsparse_int nnzb = bsr_row_ptr[mb] - bsr_row_ptr[0];

        // Create CSR arrays on device
        rocsparse_int* csr_row_ptr;
        rocsparse_int* csr_col_ind;
        float* csr_val;
        hipMalloc((void**)&csr_row_ptr, sizeof(rocsparse_int) * (m + 1));
        hipMalloc((void**)&csr_col_ind, sizeof(rocsparse_int) * nnzb * block_dim * block_dim);
        hipMalloc((void**)&csr_val, sizeof(float) * nnzb * block_dim * block_dim);

        // Create rocsparse handle
        rocsparse_local_handle handle;

        rocsparse_mat_descr bsr_descr = nullptr;
        rocsparse_create_mat_descr(&bsr_descr);

        rocsparse_mat_descr csr_descr = nullptr;
        rocsparse_create_mat_descr(&csr_descr);

        rocsparse_set_mat_index_base(bsr_descr, rocsparse_index_base_zero);
        rocsparse_set_mat_index_base(csr_descr, rocsparse_index_base_zero);

        // Format conversion
        rocsparse_sbsr2csr(handle,
                           rocsparse_direction_column,
                           mb,
                           nb,
                           bsr_descr,
                           bsr_val,
                           bsr_row_ptr,
                           bsr_col_ind,
                           block_dim,
                           csr_descr,
                           csr_val,
                           csr_row_ptr,
                           csr_col_ind);

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - dir – [in] the storage format of the blocks, rocsparse_direction_row or rocsparse_direction_column

    - mb – [in] number of block rows in the sparse BSR matrix.

    - nb – [in] number of block columns in the sparse BSR matrix.

    - bsr_descr – [in] descriptor of the sparse BSR matrix. Currently, only rocsparse_matrix_type_general is supported.

    - bsr_val – [in] array of `nnzb*block_dim*block_dim` containing the values of the sparse BSR matrix.

    - bsr_row_ptr – [in] array of `mb+1` elements that point to the start of every block row of the sparse BSR matrix.

    - bsr_col_ind – [in] array of `nnzb` elements containing the block column indices of the sparse BSR matrix.

    - block_dim – [in] size of the blocks in the sparse BSR matrix.

    - csr_descr – [in] descriptor of the sparse CSR matrix. Currently, only rocsparse_matrix_type_general is supported.

    - csr_val – [out] array of `nnzb*block_dim*block_dim` elements containing the values of the sparse CSR matrix.

    - csr_row_ptr – [out] array of `m+1` where `m=mb*block_dim` elements that point to the start of every row of the sparse CSR matrix.

    - csr_col_ind – [out] array of `nnzb*block_dim*block_dim` elements containing the column indices of the sparse CSR matrix.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `mb` or `nb` or `block_dim` is invalid.

    - rocsparse_status_invalid_pointer – `bsr_val`, `bsr_row_ptr`, `bsr_col_ind`, `csr_val`, `csr_row_ptr` or `csr_col_ind` pointer is invalid.

### rocsparse_gebsr2csr()

rocsparse_status rocsparse_sgebsr2csr(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, const rocsparse_mat_descr bsr_descr, const float *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, const rocsparse_mat_descr csr_descr, float *csr_val, rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind)

rocsparse_status rocsparse_dgebsr2csr(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, const rocsparse_mat_descr bsr_descr, const double *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, const rocsparse_mat_descr csr_descr, double *csr_val, rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind)

rocsparse_status rocsparse_cgebsr2csr(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, const rocsparse_mat_descr bsr_descr, const rocsparse_float_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, const rocsparse_mat_descr csr_descr, rocsparse_float_complex *csr_val, rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind)

rocsparse_status rocsparse_zgebsr2csr(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, const rocsparse_mat_descr bsr_descr, const rocsparse_double_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, const rocsparse_mat_descr csr_descr, rocsparse_double_complex *csr_val, rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind)

  Convert a sparse general BSR matrix into a sparse CSR matrix.

  `rocsparse_gebsr2csr` converts a BSR matrix into a CSR matrix. It is assumed, that `csr_val`, `csr_col_ind` and `csr_row_ptr` are allocated. Allocation size for `csr_row_ptr` is computed by the number of block rows multiplied by the block dimension plus one. Allocation for `csr_val` and `csr_col_ind` is computed by the the number of blocks in the BSR matrix multiplied by the product of the block dimensions.

  Example

    This example converts a general BSR matrix into an CSR matrix.

        //     1 4 0 0 0 0
        // A = 0 2 3 0 0 0
        //     5 0 0 7 8 0
        //     0 0 9 0 6 0

        rocsparse_int mb   = 2;
        rocsparse_int nb   = 2;
        rocsparse_int row_block_dim = 2;
        rocsparse_int col_block_dim = 3;
        rocsparse_int m = Mb * row_block_dim;
        rocsparse_int n = Nb * col_block_dim;

        bsr_row_ptr[mb+1]                 = {0, 1, 3};                                              // device memory
        bsr_col_ind[nnzb]                 = {0, 0, 1};                                              // device memory
        bsr_val[nnzb*block_dim*block_dim] = {1, 0, 4, 2, 0, 3, 5, 0, 0, 0, 0, 9, 7, 0, 8, 6, 0, 0}; // device memory

        rocsparse_int nnzb = bsr_row_ptr[mb] - bsr_row_ptr[0];

        // Create CSR arrays on device
        rocsparse_int* csr_row_ptr;
        rocsparse_int* csr_col_ind;
        float* csr_val;
        hipMalloc((void**)&csr_row_ptr, sizeof(rocsparse_int) * (m + 1));
        hipMalloc((void**)&csr_col_ind, sizeof(rocsparse_int) * nnzb * row_block_dim * col_block_dim);
        hipMalloc((void**)&csr_val, sizeof(float) * nnzb * row_block_dim * col_block_dim);

        // Create rocsparse handle
        rocsparse_local_handle handle;

        rocsparse_mat_descr bsr_descr = nullptr;
        rocsparse_create_mat_descr(&bsr_descr);

        rocsparse_mat_descr csr_descr = nullptr;
        rocsparse_create_mat_descr(&csr_descr);

        rocsparse_set_mat_index_base(bsr_descr, rocsparse_index_base_zero);
        rocsparse_set_mat_index_base(csr_descr, rocsparse_index_base_zero);

        // Format conversion
        rocsparse_sgebsr2csr(handle,
                           rocsparse_direction_column,
                           mb,
                           nb,
                           bsr_descr,
                           bsr_val,
                           bsr_row_ptr,
                           bsr_col_ind,
                           row_block_dim,
                           col_block_dim,
                           csr_descr,
                           csr_val,
                           csr_row_ptr,
                           csr_col_ind);

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - dir – [in] the storage format of the blocks, rocsparse_direction_row or rocsparse_direction_column

    - mb – [in] number of block rows in the sparse general BSR matrix.

    - nb – [in] number of block columns in the sparse general BSR matrix.

    - bsr_descr – [in] descriptor of the sparse general BSR matrix. Currently, only rocsparse_matrix_type_general is supported.

    - bsr_val – [in] array of `nnzb*row_block_dim*col_block_dim` containing the values of the sparse BSR matrix.

    - bsr_row_ptr – [in] array of `mb+1` elements that point to the start of every block row of the sparse BSR matrix.

    - bsr_col_ind – [in] array of `nnzb` elements containing the block column indices of the sparse BSR matrix.

    - row_block_dim – [in] row size of the blocks in the sparse general BSR matrix.

    - col_block_dim – [in] column size of the blocks in the sparse general BSR matrix.

    - csr_descr – [in] descriptor of the sparse CSR matrix. Currently, only rocsparse_matrix_type_general is supported.

    - csr_val – [out] array of `nnzb*row_block_dim*col_block_dim` elements containing the values of the sparse CSR matrix.

    - csr_row_ptr – [out] array of `m+1` where `m=mb*row_block_dim` elements that point to the start of every row of the sparse CSR matrix.

    - csr_col_ind – [out] array of `nnzb*block_dim*block_dim` elements containing the column indices of the sparse CSR matrix.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `mb` or `nb` or `block_dim` is invalid.

    - rocsparse_status_invalid_pointer – `bsr_val`, `bsr_row_ptr`, `bsr_col_ind`, `csr_val`, `csr_row_ptr` or `csr_col_ind` pointer is invalid.

### rocsparse_gebsr2gebsr_buffer_size()

rocsparse_status rocsparse_sgebsr2gebsr_buffer_size(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const rocsparse_mat_descr descr_A, const float *bsr_val_A, const rocsparse_int *bsr_row_ptr_A, const rocsparse_int *bsr_col_ind_A, rocsparse_int row_block_dim_A, rocsparse_int col_block_dim_A, rocsparse_int row_block_dim_C, rocsparse_int col_block_dim_C, size_t *buffer_size)

rocsparse_status rocsparse_dgebsr2gebsr_buffer_size(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const rocsparse_mat_descr descr_A, const double *bsr_val_A, const rocsparse_int *bsr_row_ptr_A, const rocsparse_int *bsr_col_ind_A, rocsparse_int row_block_dim_A, rocsparse_int col_block_dim_A, rocsparse_int row_block_dim_C, rocsparse_int col_block_dim_C, size_t *buffer_size)

rocsparse_status rocsparse_cgebsr2gebsr_buffer_size(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const rocsparse_mat_descr descr_A, const rocsparse_float_complex *bsr_val_A, const rocsparse_int *bsr_row_ptr_A, const rocsparse_int *bsr_col_ind_A, rocsparse_int row_block_dim_A, rocsparse_int col_block_dim_A, rocsparse_int row_block_dim_C, rocsparse_int col_block_dim_C, size_t *buffer_size)

rocsparse_status rocsparse_zgebsr2gebsr_buffer_size(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const rocsparse_mat_descr descr_A, const rocsparse_double_complex *bsr_val_A, const rocsparse_int *bsr_row_ptr_A, const rocsparse_int *bsr_col_ind_A, rocsparse_int row_block_dim_A, rocsparse_int col_block_dim_A, rocsparse_int row_block_dim_C, rocsparse_int col_block_dim_C, size_t *buffer_size)

  This function computes the the size of the user allocated temporary storage buffer used when converting a sparse general BSR matrix to another sparse general BSR matrix.

  `rocsparse_gebsr2gebsr_buffer_size` returns the size of the temporary storage buffer that is required by rocsparse_gebsr2gebsr_nnz(), rocsparse_sgebsr2gebsr(), rocsparse_dgebsr2gebsr(), rocsparse_cgebsr2gebsr(), and rocsparse_zgebsr2gebsr(). The temporary storage buffer must be allocated by the user.

  Note

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

  Note

  This routine supports execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - dir – [in] the storage format of the blocks, rocsparse_direction_row or rocsparse_direction_column

    - mb – [in] number of block rows of the general BSR sparse matrix `A`.

    - nb – [in] number of block columns of the general BSR sparse matrix `A`.

    - nnzb – [in] number of blocks in the general BSR sparse matrix `A`.

    - descr_A – [in] the descriptor of the general BSR sparse matrix `A`, the supported matrix type is rocsparse_matrix_type_general and also any valid value of the rocsparse_index_base.

    - bsr_val_A – [in] array of `nnzb*row_block_dim_A*col_block_dim_A` containing the values of the sparse general BSR matrix `A`.

    - bsr_row_ptr_A – [in] array of `mb+1` elements that point to the start of every block row of the sparse general BSR matrix `A`.

    - bsr_col_ind_A – [in] array of `nnzb` elements containing the block column indices of the sparse general BSR matrix `A`.

    - row_block_dim_A – [in] row size of the blocks in the sparse general BSR matrix `A`.

    - col_block_dim_A – [in] column size of the blocks in the sparse general BSR matrix `A`.

    - row_block_dim_C – [in] row size of the blocks in the sparse general BSR matrix `C`.

    - col_block_dim_C – [in] column size of the blocks in the sparse general BSR matrix `C`.

    - buffer_size – [out] number of bytes of the temporary storage buffer required by rocsparse_gebsr2gebsr_nnz(), rocsparse_sgebsr2gebsr(), rocsparse_dgebsr2gebsr(), rocsparse_cgebsr2gebsr(), and rocsparse_zgebsr2gebsr().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `mb` or `nb` or `nnzb` or `row_block_dim_A` or `col_block_dim_A` or `row_block_dim_C` or `col_block_dim_C` is invalid.

    - rocsparse_status_invalid_pointer – `bsr_row_ptr_A` or `bsr_col_ind_A` or `descr_A` or `buffer_size` pointer is invalid.

### rocsparse_gebsr2gebsr_nnz()

rocsparse_status rocsparse_gebsr2gebsr_nnz(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const rocsparse_mat_descr descr_A, const rocsparse_int *bsr_row_ptr_A, const rocsparse_int *bsr_col_ind_A, rocsparse_int row_block_dim_A, rocsparse_int col_block_dim_A, const rocsparse_mat_descr descr_C, rocsparse_int *bsr_row_ptr_C, rocsparse_int row_block_dim_C, rocsparse_int col_block_dim_C, rocsparse_int *nnz_total_dev_host_ptr, void *temp_buffer)

  This function is used when converting a general BSR sparse matrix `A` to another general BSR sparse matrix `C`. Specifically, this function determines the number of non-zero blocks that will exist in `C` (stored using either a host or device pointer), and computes the row pointer array for `C`.

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - dir – [in] the storage format of the blocks, rocsparse_direction_row or rocsparse_direction_column

    - mb – [in] number of block rows of the general BSR sparse matrix `A`.

    - nb – [in] number of block columns of the general BSR sparse matrix `A`.

    - nnzb – [in] number of blocks in the general BSR sparse matrix `A`.

    - descr_A – [in] the descriptor of the general BSR sparse matrix `A`, the supported matrix type is rocsparse_matrix_type_general and also any valid value of the rocsparse_index_base.

    - bsr_row_ptr_A – [in] array of `mb+1` elements that point to the start of every block row of the sparse general BSR matrix `A`.

    - bsr_col_ind_A – [in] array of `nnzb` elements containing the block column indices of the sparse general BSR matrix `A`.

    - row_block_dim_A – [in] row size of the blocks in the sparse general BSR matrix `A`.

    - col_block_dim_A – [in] column size of the blocks in the sparse general BSR matrix `A`.

    - descr_C – [in] the descriptor of the general BSR sparse matrix `C`, the supported matrix type is rocsparse_matrix_type_general and also any valid value of the rocsparse_index_base.

    - bsr_row_ptr_C – [in] array of `mb_C+1` elements that point to the start of every block row of the sparse general BSR matrix `C` where `mb_C=`(m+row_block_dim_C-1)/row_block_dim_C.

    - row_block_dim_C – [in] row size of the blocks in the sparse general BSR matrix `C`.

    - col_block_dim_C – [in] column size of the blocks in the sparse general BSR matrix `C`.

    - nnz_total_dev_host_ptr – [out] total number of nonzero blocks in general BSR sparse matrix `C` stored using device or host memory.

    - temp_buffer – [out] buffer allocated by the user whose size is determined by calling rocsparse_xgebsr2gebsr_buffer_size().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `mb` or `nb` or `nnzb` or `row_block_dim_A` or `col_block_dim_A` or `row_block_dim_C` or `col_block_dim_C` is invalid.

    - rocsparse_status_invalid_pointer – `bsr_row_ptr_A` or `bsr_col_ind_A` or `bsr_row_ptr_C` or `descr_A` or `descr_C` or `temp_buffer` pointer is invalid.

### rocsparse_gebsr2gebsr()

rocsparse_status rocsparse_sgebsr2gebsr(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const rocsparse_mat_descr descr_A, const float *bsr_val_A, const rocsparse_int *bsr_row_ptr_A, const rocsparse_int *bsr_col_ind_A, rocsparse_int row_block_dim_A, rocsparse_int col_block_dim_A, const rocsparse_mat_descr descr_C, float *bsr_val_C, rocsparse_int *bsr_row_ptr_C, rocsparse_int *bsr_col_ind_C, rocsparse_int row_block_dim_C, rocsparse_int col_block_dim_C, void *temp_buffer)

rocsparse_status rocsparse_dgebsr2gebsr(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const rocsparse_mat_descr descr_A, const double *bsr_val_A, const rocsparse_int *bsr_row_ptr_A, const rocsparse_int *bsr_col_ind_A, rocsparse_int row_block_dim_A, rocsparse_int col_block_dim_A, const rocsparse_mat_descr descr_C, double *bsr_val_C, rocsparse_int *bsr_row_ptr_C, rocsparse_int *bsr_col_ind_C, rocsparse_int row_block_dim_C, rocsparse_int col_block_dim_C, void *temp_buffer)

rocsparse_status rocsparse_cgebsr2gebsr(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const rocsparse_mat_descr descr_A, const rocsparse_float_complex *bsr_val_A, const rocsparse_int *bsr_row_ptr_A, const rocsparse_int *bsr_col_ind_A, rocsparse_int row_block_dim_A, rocsparse_int col_block_dim_A, const rocsparse_mat_descr descr_C, rocsparse_float_complex *bsr_val_C, rocsparse_int *bsr_row_ptr_C, rocsparse_int *bsr_col_ind_C, rocsparse_int row_block_dim_C, rocsparse_int col_block_dim_C, void *temp_buffer)

rocsparse_status rocsparse_zgebsr2gebsr(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const rocsparse_mat_descr descr_A, const rocsparse_double_complex *bsr_val_A, const rocsparse_int *bsr_row_ptr_A, const rocsparse_int *bsr_col_ind_A, rocsparse_int row_block_dim_A, rocsparse_int col_block_dim_A, const rocsparse_mat_descr descr_C, rocsparse_double_complex *bsr_val_C, rocsparse_int *bsr_row_ptr_C, rocsparse_int *bsr_col_ind_C, rocsparse_int row_block_dim_C, rocsparse_int col_block_dim_C, void *temp_buffer)

  This function converts the general BSR sparse matrix `A` to another general BSR sparse matrix `C`.

  The conversion uses three steps. First, the user calls rocsparse_xgebsr2gebsr_buffer_size() to determine the size of the required temporary storage buffer. The user then allocates this buffer. Secondly, the user then allocates `mb_C+1` integers for the row pointer array for `C` where `mb_C=`(m+row_block_dim_C-1)/row_block_dim_C. The user then calls rocsparse_xgebsr2gebsr_nnz() to fill in the row pointer array for `C` ( `bsr_row_ptr_C` ) and determine the number of non-zero blocks that will exist in `C`. Finally, the user allocates space for the colimn indices array of `C` to have `nnzb_C` elements and space for the values array of `C` to have `nnzb_C*roc_block_dim_C*col_block_dim_C` and then calls rocsparse_xgebsr2gebsr() to complete the conversion.

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - dir – [in] the storage format of the blocks, rocsparse_direction_row or rocsparse_direction_column

    - mb – [in] number of block rows of the general BSR sparse matrix `A`.

    - nb – [in] number of block columns of the general BSR sparse matrix `A`.

    - nnzb – [in] number of blocks in the general BSR sparse matrix `A`.

    - descr_A – [in] the descriptor of the general BSR sparse matrix `A`, the supported matrix type is rocsparse_matrix_type_general and also any valid value of the rocsparse_index_base.

    - bsr_val_A – [in] array of `nnzb*row_block_dim_A*col_block_dim_A` containing the values of the sparse general BSR matrix `A`.

    - bsr_row_ptr_A – [in] array of `mb+1` elements that point to the start of every block row of the sparse general BSR matrix `A`.

    - bsr_col_ind_A – [in] array of `nnzb` elements containing the block column indices of the sparse general BSR matrix `A`.

    - row_block_dim_A – [in] row size of the blocks in the sparse general BSR matrix `A`.

    - col_block_dim_A – [in] column size of the blocks in the sparse general BSR matrix `A`.

    - descr_C – [in] the descriptor of the general BSR sparse matrix `C`, the supported matrix type is rocsparse_matrix_type_general and also any valid value of the rocsparse_index_base.

    - bsr_val_C – [in] array of `nnzb_C*row_block_dim_C*col_block_dim_C` containing the values of the sparse general BSR matrix `C`.

    - bsr_row_ptr_C – [in] array of `mb_C+1` elements that point to the start of every block row of the sparse general BSR matrix `C`.

    - bsr_col_ind_C – [in] array of `nnzb_C` elements containing the block column indices of the sparse general BSR matrix `C`.

    - row_block_dim_C – [in] row size of the blocks in the sparse general BSR matrix `C`.

    - col_block_dim_C – [in] column size of the blocks in the sparse general BSR matrix `C`.

    - temp_buffer – [out] buffer allocated by the user whose size is determined by calling rocsparse_xgebsr2gebsr_buffer_size().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `mb` or `nb` or `nnzb` or `row_block_dim_A` or `col_block_dim_A` or `row_block_dim_C` or `col_block_dim_C` is invalid.

    - rocsparse_status_invalid_pointer – `bsr_row_ptr_A` or `bsr_col_ind_A` or `bsr_val_A` or `bsr_row_ptr_C` or `bsr_col_ind_C` or `bsr_val_C` or `descr_A` or `descr_C` or `temp_buffer` pointer is invalid.

### rocsparse_csr2bsr_nnz()

rocsparse_status rocsparse_csr2bsr_nnz(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr csr_descr, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_int block_dim, const rocsparse_mat_descr bsr_descr, rocsparse_int *bsr_row_ptr, rocsparse_int *bsr_nnz)

  This function computes the number of nonzero block columns per row and the total number of nonzero blocks in a sparse BSR matrix given a sparse CSR matrix as input.

  The routine does support asynchronous execution if the pointer mode is set to device.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - dir – [in] direction that specified whether to count nonzero elements by rocsparse_direction_row or by rocsparse_direction_row.

    - m – [in] number of rows of the sparse CSR matrix.

    - n – [in] number of columns of the sparse CSR matrix.

    - csr_descr – [in] descriptor of the sparse CSR matrix. Currently, only rocsparse_matrix_type_general is supported.

    - csr_row_ptr – [in] integer array containing `m+1` elements that point to the start of each row of the CSR matrix

    - csr_col_ind – [in] integer array of the column indices for each non-zero element in the CSR matrix

    - block_dim – [in] the block dimension of the BSR matrix. Between 1 and min(m, n)

    - bsr_descr – [in] descriptor of the sparse BSR matrix. Currently, only rocsparse_matrix_type_general is supported.

    - bsr_row_ptr – [out] integer array containing `mb+1` elements that point to the start of each block row of the BSR matrix

    - bsr_nnz – [out] total number of nonzero elements in device or host memory.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m` or `n` or `block_dim` is invalid.

    - rocsparse_status_invalid_pointer – `csr_row_ptr` or `csr_col_ind` or `bsr_row_ptr` or `bsr_nnz` pointer is invalid.

### rocsparse_csr2bsr()

rocsparse_status rocsparse_scsr2bsr(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr csr_descr, const float *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_int block_dim, const rocsparse_mat_descr bsr_descr, float *bsr_val, rocsparse_int *bsr_row_ptr, rocsparse_int *bsr_col_ind)

rocsparse_status rocsparse_dcsr2bsr(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr csr_descr, const double *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_int block_dim, const rocsparse_mat_descr bsr_descr, double *bsr_val, rocsparse_int *bsr_row_ptr, rocsparse_int *bsr_col_ind)

rocsparse_status rocsparse_ccsr2bsr(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr csr_descr, const rocsparse_float_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_int block_dim, const rocsparse_mat_descr bsr_descr, rocsparse_float_complex *bsr_val, rocsparse_int *bsr_row_ptr, rocsparse_int *bsr_col_ind)

rocsparse_status rocsparse_zcsr2bsr(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr csr_descr, const rocsparse_double_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_int block_dim, const rocsparse_mat_descr bsr_descr, rocsparse_double_complex *bsr_val, rocsparse_int *bsr_row_ptr, rocsparse_int *bsr_col_ind)

  Convert a sparse CSR matrix into a sparse BSR matrix.

  `rocsparse_csr2bsr` converts a CSR matrix into a BSR matrix. It is assumed, that `bsr_val`, `bsr_col_ind` and `bsr_row_ptr` are allocated. Allocation size for `bsr_row_ptr` is computed as `mb+1` where `mb` is the number of block rows in the BSR matrix. Allocation size for `bsr_val` and `bsr_col_ind` is computed using `csr2bsr_nnz()` which also fills in `bsr_row_ptr`.

  `rocsparse_csr2bsr` requires extra temporary storage that is allocated internally if `block_dim>16`

  Example

    This example converts a CSR matrix into an BSR matrix.

        //     1 4 0 0 0 0
        // A = 0 2 3 0 0 0
        //     5 0 0 7 8 0
        //     0 0 9 0 6 0

        rocsparse_int m   = 4;
        rocsparse_int n   = 6;
        rocsparse_int block_dim = 2;
        rocsparse_int nnz = 9;
        rocsparse_int mb = (m + block_dim - 1) / block_dim;
        rocsparse_int nb = (n + block_dim - 1) / block_dim;

        csr_row_ptr[m+1]  = {0, 2, 4, 7, 9};             // device memory
        csr_col_ind[nnz]  = {0, 1, 1, 2, 0, 3, 4, 2, 4}; // device memory
        csr_val[nnz]      = {1, 4, 2, 3, 5, 7, 8, 9, 6}; // device memory

        hipMalloc(&bsr_row_ptr, sizeof(rocsparse_int) *(mb + 1));
        rocsparse_int nnzb;
        rocsparse_int* nnzTotalHostPtr = &nnzb;
        csr2bsr_nnz(handle,
                    rocsparse_direction_row,
                    m,
                    n,
                    csr_descr,
                    csr_row_ptr,
                    csr_col_ind,
                    block_dim,
                    bsr_descr,
                    bsr_row_ptr,
                    nnzTotalHostPtr);
        nnzb = *nnzTotalDevHostPtr;
        hipMalloc(&bsr_col_ind, sizeof(int)*nnzb);
        hipMalloc(&bsr_val, sizeof(float)*(block_dim * block_dim) * nnzb);
        scsr2bsr(handle,
                 rocsparse_direction_row,
                 m,
                 n,
                 csr_descr,
                 csr_val,
                 csr_row_ptr,
                 csr_col_ind,
                 block_dim,
                 bsr_descr,
                 bsr_val,
                 bsr_row_ptr,
                 bsr_col_ind);

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - dir – [in] the storage format of the blocks, rocsparse_direction_row or rocsparse_direction_column

    - m – [in] number of rows in the sparse CSR matrix.

    - n – [in] number of columns in the sparse CSR matrix.

    - csr_descr – [in] descriptor of the sparse CSR matrix. Currently, only rocsparse_matrix_type_general is supported.

    - csr_val – [in] array of `nnz` elements containing the values of the sparse CSR matrix.

    - csr_row_ptr – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix.

    - csr_col_ind – [in] array of `nnz` elements containing the column indices of the sparse CSR matrix.

    - block_dim – [in] size of the blocks in the sparse BSR matrix.

    - bsr_descr – [in] descriptor of the sparse BSR matrix. Currently, only rocsparse_matrix_type_general is supported.

    - bsr_val – [out] array of `nnzb*block_dim*block_dim` containing the values of the sparse BSR matrix.

    - bsr_row_ptr – [out] array of `mb+1` elements that point to the start of every block row of the sparse BSR matrix.

    - bsr_col_ind – [out] array of `nnzb` elements containing the block column indices of the sparse BSR matrix.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m` or `n` or `block_dim` is invalid.

    - rocsparse_status_invalid_pointer – `bsr_val`, `bsr_row_ptr`, `bsr_col_ind`, `csr_val`, `csr_row_ptr` or `csr_col_ind` pointer is invalid.

### rocsparse_csr2gebsr_nnz()

rocsparse_status rocsparse_csr2gebsr_nnz(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr csr_descr, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, const rocsparse_mat_descr bsr_descr, rocsparse_int *bsr_row_ptr, rocsparse_int row_block_dim, rocsparse_int col_block_dim, rocsparse_int *bsr_nnz_devhost, void *temp_buffer)

  This function computes the number of nonzero block columns per row and the total number of nonzero blocks in a sparse GEneral BSR matrix given a sparse CSR matrix as input.

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - dir – [in] direction that specified whether to count nonzero elements by rocsparse_direction_row or by rocsparse_direction_row.

    - m – [in] number of rows of the sparse CSR matrix.

    - n – [in] number of columns of the sparse CSR matrix.

    - csr_descr – [in] descriptor of the sparse CSR matrix. Currently, only rocsparse_matrix_type_general is supported.

    - csr_row_ptr – [in] integer array containing `m+1` elements that point to the start of each row of the CSR matrix

    - csr_col_ind – [in] integer array of the column indices for each non-zero element in the CSR matrix

    - bsr_descr – [in] descriptor of the sparse GEneral BSR matrix. Currently, only rocsparse_matrix_type_general is supported.

    - bsr_row_ptr – [out] integer array containing `mb+1` elements that point to the start of each block row of the General BSR matrix

    - row_block_dim – [in] the row block dimension of the GEneral BSR matrix. Between 1 and min(m, n)

    - col_block_dim – [in] the col block dimension of the GEneral BSR matrix. Between 1 and min(m, n)

    - bsr_nnz_devhost – [out] total number of nonzero elements in device or host memory.

    - temp_buffer – [in] buffer allocated by the user whose size is determined by calling `rocsparse_xcsr2gebsr_buffer_size`.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m` or `n` or `row_block_dim` `col_block_dim` is invalid.

    - rocsparse_status_invalid_pointer – `csr_row_ptr` or `csr_col_ind` or `bsr_row_ptr` or `bsr_nnz_devhost` pointer is invalid.

### rocsparse_csr2gebsr_buffer_size()

rocsparse_status rocsparse_scsr2gebsr_buffer_size(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr csr_descr, const float *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, size_t *buffer_size)

rocsparse_status rocsparse_dcsr2gebsr_buffer_size(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr csr_descr, const double *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, size_t *buffer_size)

rocsparse_status rocsparse_ccsr2gebsr_buffer_size(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr csr_descr, const rocsparse_float_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, size_t *buffer_size)

rocsparse_status rocsparse_zcsr2gebsr_buffer_size(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr csr_descr, const rocsparse_double_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, size_t *buffer_size)

  `rocsparse_csr2gebsr_buffer_size` returns the size of the temporary buffer that is required by `rocsparse_csr2gebcsr_nnz`, `rocsparse_scsr2gebcsr`, `rocsparse_dcsr2gebsr`, `rocsparse_ccsr2gebsr` and `rocsparse_zcsr2gebsr`. The temporary storage buffer must be allocated by the user.

  This function computes the number of nonzero block columns per row and the total number of nonzero blocks in a sparse GEneral BSR matrix given a sparse CSR matrix as input.

  Note

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

  Note

  This routine supports execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - dir – [in] direction that specified whether to count nonzero elements by rocsparse_direction_row or by rocsparse_direction_row.

    - m – [in] number of rows of the sparse CSR matrix.

    - n – [in] number of columns of the sparse CSR matrix.

    - csr_descr – [in] descriptor of the sparse CSR matrix. Currently, only rocsparse_matrix_type_general is supported.

    - csr_val – [in] array of `nnz` elements containing the values of the sparse CSR matrix.

    - csr_row_ptr – [in] integer array containing `m+1` elements that point to the start of each row of the CSR matrix

    - csr_col_ind – [in] integer array of the column indices for each non-zero element in the CSR matrix

    - row_block_dim – [in] the row block dimension of the GEneral BSR matrix. Between 1 and `m`

    - col_block_dim – [in] the col block dimension of the GEneral BSR matrix. Between 1 and `n`

    - buffer_size – [out] number of bytes of the temporary storage buffer required by `rocsparse_csr2gebsr_nnz` and `rocsparse_Xcsr2gebsr`.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m` or `n` or `row_block_dim` `col_block_dim` is invalid.

    - rocsparse_status_invalid_pointer – `csr_val` or `csr_row_ptr` or `csr_col_ind` or `bsr_row_ptr` or `buffer_size` pointer is invalid.

### rocsparse_csr2gebsr()

rocsparse_status rocsparse_scsr2gebsr(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr csr_descr, const float *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, const rocsparse_mat_descr bsr_descr, float *bsr_val, rocsparse_int *bsr_row_ptr, rocsparse_int *bsr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, void *temp_buffer)

rocsparse_status rocsparse_dcsr2gebsr(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr csr_descr, const double *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, const rocsparse_mat_descr bsr_descr, double *bsr_val, rocsparse_int *bsr_row_ptr, rocsparse_int *bsr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, void *temp_buffer)

rocsparse_status rocsparse_ccsr2gebsr(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr csr_descr, const rocsparse_float_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, const rocsparse_mat_descr bsr_descr, rocsparse_float_complex *bsr_val, rocsparse_int *bsr_row_ptr, rocsparse_int *bsr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, void *temp_buffer)

rocsparse_status rocsparse_zcsr2gebsr(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr csr_descr, const rocsparse_double_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, const rocsparse_mat_descr bsr_descr, rocsparse_double_complex *bsr_val, rocsparse_int *bsr_row_ptr, rocsparse_int *bsr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, void *temp_buffer)

  Convert a sparse CSR matrix into a sparse GEneral BSR matrix.

  `rocsparse_csr2gebsr` converts a CSR matrix into a GEneral BSR matrix. It is assumed, that `bsr_val`, `bsr_col_ind` and `bsr_row_ptr` are allocated. Allocation size for `bsr_row_ptr` is computed as `mb+1` where `mb` is the number of block rows in the GEneral BSR matrix. Allocation size for `bsr_val` and `bsr_col_ind` is computed using `csr2gebsr_nnz()` which also fills in `bsr_row_ptr`.

  Example

    This example converts a CSR matrix into an BSR matrix.

        //     1 4 0 0 0 0
        // A = 0 2 3 0 0 0
        //     5 0 0 7 8 0
        //     0 0 9 0 6 0

        rocsparse_int m   = 4;
        rocsparse_int n   = 6;
        rocsparse_int row_block_dim = 2;
        rocsparse_int col_block_dim = 3;
        rocsparse_int nnz = 9;
        rocsparse_int mb = (m + row_block_dim - 1) / row_block_dim;
        rocsparse_int nb = (n + col_block_dim - 1) / col_block_dim;

        csr_row_ptr[m+1]  = {0, 2, 4, 7, 9};             // device memory
        csr_col_ind[nnz]  = {0, 1, 1, 2, 0, 3, 4, 2, 4}; // device memory
        csr_val[nnz]      = {1, 4, 2, 3, 5, 7, 8, 9, 6}; // device memory

        hipMalloc(&bsr_row_ptr, sizeof(rocsparse_int) *(mb + 1));
        rocsparse_int nnzb;
        rocsparse_int* nnzTotalHostPtr = &nnzb;
        csr2gebsr_nnz(handle,
                    rocsparse_direction_row,
                    m,
                    n,
                    csr_descr,
                    csr_row_ptr,
                    csr_col_ind,
                    row_block_dim,
                    col_block_dim,
                    bsr_descr,
                    bsr_row_ptr,
                    nnzTotalHostPtr);
        nnzb = *nnzTotalHostPtr;
        hipMalloc(&bsr_col_ind, sizeof(int)*nnzb);
        hipMalloc(&bsr_val, sizeof(float)*(row_block_dim * col_block_dim) * nnzb);
        scsr2gebsr(handle,
                 rocsparse_direction_row,
                 m,
                 n,
                 csr_descr,
                 csr_val,
                 csr_row_ptr,
                 csr_col_ind,
                 row_block_dim,
                 col_block_dim,
                 bsr_descr,
                 bsr_val,
                 bsr_row_ptr,
                 bsr_col_ind);

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - dir – [in] the storage format of the blocks, rocsparse_direction_row or rocsparse_direction_column

    - m – [in] number of rows in the sparse CSR matrix.

    - n – [in] number of columns in the sparse CSR matrix.

    - csr_descr – [in] descriptor of the sparse CSR matrix. Currently, only rocsparse_matrix_type_general is supported.

    - csr_val – [in] array of `nnz` elements containing the values of the sparse CSR matrix.

    - csr_row_ptr – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix.

    - csr_col_ind – [in] array of `nnz` elements containing the column indices of the sparse CSR matrix.

    - bsr_descr – [in] descriptor of the sparse BSR matrix. Currently, only rocsparse_matrix_type_general is supported.

    - bsr_val – [out] array of `nnzb*` `row_block_dim*` `col_block_dim` containing the values of the sparse BSR matrix.

    - bsr_row_ptr – [out] array of `mb+1` elements that point to the start of every block row of the sparse BSR matrix.

    - bsr_col_ind – [out] array of `nnzb` elements containing the block column indices of the sparse BSR matrix.

    - row_block_dim – [in] row size of the blocks in the sparse GEneral BSR matrix.

    - col_block_dim – [in] col size of the blocks in the sparse GEneral BSR matrix.

    - temp_buffer – [in] buffer allocated by the user whose size is determined by calling `rocsparse_xcsr2gebsr_buffer_size`.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m` or `n` or `row_block_dim` or `col_block_dim` is invalid.

    - rocsparse_status_invalid_pointer – `bsr_val`, `bsr_row_ptr`, `bsr_col_ind`, `csr_val`, `csr_row_ptr` or `csr_col_ind` pointer is invalid.

### rocsparse_csr2csr_compress()

rocsparse_status rocsparse_scsr2csr_compress(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr_A, const float *csr_val_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, rocsparse_int nnz_A, const rocsparse_int *nnz_per_row, float *csr_val_C, rocsparse_int *csr_row_ptr_C, rocsparse_int *csr_col_ind_C, float tol)

rocsparse_status rocsparse_dcsr2csr_compress(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr_A, const double *csr_val_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, rocsparse_int nnz_A, const rocsparse_int *nnz_per_row, double *csr_val_C, rocsparse_int *csr_row_ptr_C, rocsparse_int *csr_col_ind_C, double tol)

rocsparse_status rocsparse_ccsr2csr_compress(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr_A, const rocsparse_float_complex *csr_val_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, rocsparse_int nnz_A, const rocsparse_int *nnz_per_row, rocsparse_float_complex *csr_val_C, rocsparse_int *csr_row_ptr_C, rocsparse_int *csr_col_ind_C, rocsparse_float_complex tol)

rocsparse_status rocsparse_zcsr2csr_compress(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr_A, const rocsparse_double_complex *csr_val_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, rocsparse_int nnz_A, const rocsparse_int *nnz_per_row, rocsparse_double_complex *csr_val_C, rocsparse_int *csr_row_ptr_C, rocsparse_int *csr_col_ind_C, rocsparse_double_complex tol)

  Convert a sparse CSR matrix into a compressed sparse CSR matrix.

  `rocsparse_csr2csr_compress` converts a CSR matrix into a compressed CSR matrix by removing entries in the input CSR matrix that are below a non-negative threshold `tol`

  Example

    This example demonstrates how to compress a CSR matrix. Compressing a CSR matrix involves two steps. First we use nnz_compress() to determine how many entries will be in the final compressed CSR matrix. Then we call csr2csr_compress() to finish the compression and fill in the column indices and values arrays of the compressed CSR matrix.

        //     1 2 0 3 0
        // A = 0 4 5 0 0
        //     6 0 0 7 8

        float tol = 0.0f;

        rocsparse_int m     = 3;
        rocsparse_int n     = 5;
        rocsparse_int nnz_A = 8;

        csr_row_ptr_A[m+1]   = {0, 3, 5, 8};             // device memory
        csr_col_ind_A[nnz_A] = {0, 1, 3, 1, 2, 0, 3, 4}; // device memory
        csr_val_A[nnz_A]     = {1, 0, 3, 4, 0, 6, 7, 0}; // device memory

        // Allocate memory for the row pointer array of the compressed CSR matrix
        rocsparse_int* csr_row_ptr_C;
        hipMalloc(csr_row_ptr_C, sizeof(rocsparse_int) * (m + 1));

        // Allocate memory for the nnz_per_row array
        rocsparse_int* nnz_per_row;
        hipMalloc(nnz_per_row, sizeof(rocsparse_int) * m);

        // Call nnz_compress() which fills in nnz_per_row array and finds the number
        // of entries that will be in the compressed CSR matrix
        rocsparse_int nnz_C;
        nnz_compress(handle,
                     m,
                     descr_A,
                     csr_val_A,
                     csr_row_ptr_A,
                     nnz_per_row,
                     &nnz_C,
                     tol);

        // Allocate column indices and values array for the compressed CSR matrix
        rocsparse_int* csr_col_ind_C;
        rocsparse_int* csr_val_C;
        hipMalloc(csr_col_ind_C, sizeof(rocsparse_int) * nnz_C;
        hipMalloc(csr_val_C, sizeof(rocsparse_int) * nnz_C;

        // Finish compression by calling csr2csr_compress()
        csr2csr_compress(handle,
                         m,
                         n,
                         descr_A,
                         csr_val_A,
                         csr_row_ptr_A,
                         csr_col_ind_A,
                         nnz_A,
                         nnz_per_row,
                         csr_val_C,
                         csr_row_ptr_C,
                         csr_col_ind_C,
                         tol);

  Note

  In the case of complex matrices only the magnitude of the real part of `tol` is used.

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows of the sparse CSR matrix.

    - n – [in] number of columns of the sparse CSR matrix.

    - descr_A – [in] matrix descriptor for the CSR matrix

    - csr_val_A – [in] array of `nnz_A` elements of the sparse CSR matrix.

    - csr_row_ptr_A – [in] array of `m+1` elements that point to the start of every row of the uncompressed sparse CSR matrix.

    - csr_col_ind_A – [in] array of `nnz_A` elements containing the column indices of the uncompressed sparse CSR matrix.

    - nnz_A – [in] number of elements in the column indices and values arrays of the uncompressed sparse CSR matrix.

    - nnz_per_row – [in] array of length `m` containing the number of entries that will be kept per row in the final compressed CSR matrix.

    - csr_val_C – [out] array of `nnz_C` elements of the compressed sparse CSC matrix.

    - csr_row_ptr_C – [out] array of `m+1` elements that point to the start of every column of the compressed sparse CSR matrix.

    - csr_col_ind_C – [out] array of `nnz_C` elements containing the row indices of the compressed sparse CSR matrix.

    - tol – [in] the non-negative tolerance used for compression. If `tol` is complex then only the magnitude of the real part is used. Entries in the input uncompressed CSR array that are below the tolerance are removed in output compressed CSR matrix.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m`, `n` or `nnz_A` is invalid.

    - rocsparse_status_invalid_value – `tol` is invalid.

    - rocsparse_status_invalid_pointer – `csr_val_A`, `csr_row_ptr_A`, `csr_col_ind_A`, `csr_val_C`, `csr_row_ptr_C`, `csr_col_ind_C` or `nnz_per_row` pointer is invalid.

### rocsparse_create_identity_permutation()

rocsparse_status rocsparse_create_identity_permutation(rocsparse_handle handle, rocsparse_int n, rocsparse_int *p)

  Create the identity map.

  `rocsparse_create_identity_permutation` stores the identity map in `p`, such that \(p = 0:1:(n-1)\).

      for(i = 0; i < n; ++i)
      {
          p[i] = i;
      }

  Example

    The following example creates an identity permutation.

        rocsparse_int size = 200;

        // Allocate memory to hold the identity map
        rocsparse_int* perm;
        hipMalloc((void**)&perm, sizeof(rocsparse_int) * size);

        // Fill perm with the identity permutation
        rocsparse_create_identity_permutation(handle, size, perm);

  Note

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

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - n – [in] size of the map `p`.

    - p – [out] array of `n` integers containing the map.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `n` is invalid.

    - rocsparse_status_invalid_pointer – `p` pointer is invalid.

### rocsparse_csrsort_buffer_size()

rocsparse_status rocsparse_csrsort_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, size_t *buffer_size)

  Sort a sparse CSR matrix.

  `rocsparse_csrsort_buffer_size` returns the size of the temporary storage buffer required by rocsparse_csrsort(). The temporary storage buffer must be allocated by the user.

  Note

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

  Note

  This routine supports execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows of the sparse CSR matrix.

    - n – [in] number of columns of the sparse CSR matrix.

    - nnz – [in] number of non-zero entries of the sparse CSR matrix.

    - csr_row_ptr – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix.

    - csr_col_ind – [in] array of `nnz` elements containing the column indices of the sparse CSR matrix.

    - buffer_size – [out] number of bytes of the temporary storage buffer required by rocsparse_csrsort().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m`, `n` or `nnz` is invalid.

    - rocsparse_status_invalid_pointer – `csr_row_ptr`, `csr_col_ind` or `buffer_size` pointer is invalid.

### rocsparse_csrsort()

rocsparse_status rocsparse_csrsort(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const rocsparse_mat_descr descr, const rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind, rocsparse_int *perm, void *temp_buffer)

  Sort a sparse CSR matrix.

  `rocsparse_csrsort` sorts a matrix in CSR format. The sorted permutation vector `perm` can be used to obtain sorted `csr_val` array. In this case, `perm` must be initialized as the identity permutation, see rocsparse_create_identity_permutation().

  `rocsparse_csrsort` requires extra temporary storage buffer that has to be allocated by the user. Storage buffer size can be determined by rocsparse_csrsort_buffer_size().

  Example

    The following example sorts a \(3 \times 3\) CSR matrix.

        //     1 2 3
        // A = 4 5 6
        //     7 8 9
        rocsparse_int m   = 3;
        rocsparse_int n   = 3;
        rocsparse_int nnz = 9;

        csr_row_ptr[m + 1] = {0, 3, 6, 9};                // device memory
        csr_col_ind[nnz]   = {2, 0, 1, 0, 1, 2, 0, 2, 1}; // device memory
        csr_val[nnz]       = {3, 1, 2, 4, 5, 6, 7, 9, 8}; // device memory

        // Create permutation vector perm as the identity map
        rocsparse_int* perm;
        hipMalloc((void**)&perm, sizeof(rocsparse_int) * nnz);
        rocsparse_create_identity_permutation(handle, nnz, perm);

        // Allocate temporary buffer
        size_t buffer_size;
        void* temp_buffer;
        rocsparse_csrsort_buffer_size(handle, m, n, nnz, csr_row_ptr, csr_col_ind, &buffer_size);
        hipMalloc(&temp_buffer, buffer_size);

        // Sort the CSR matrix
        rocsparse_csrsort(handle, m, n, nnz, descr, csr_row_ptr, csr_col_ind, perm, temp_buffer);

        // Gather sorted csr_val array
        float* csr_val_sorted;
        hipMalloc((void**)&csr_val_sorted, sizeof(float) * nnz);
        rocsparse_sgthr(handle, nnz, csr_val, csr_val_sorted, perm, rocsparse_index_base_zero);

        // Clean up
        hipFree(temp_buffer);
        hipFree(perm);
        hipFree(csr_val);

  Note

  `perm` can be `NULL` if a sorted permutation vector is not required.

  Note

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

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows of the sparse CSR matrix.

    - n – [in] number of columns of the sparse CSR matrix.

    - nnz – [in] number of non-zero entries of the sparse CSR matrix.

    - descr – [in] descriptor of the sparse CSR matrix. Currently, only rocsparse_matrix_type_general is supported.

    - csr_row_ptr – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix.

    - csr_col_ind – [inout] array of `nnz` elements containing the column indices of the sparse CSR matrix.

    - perm – [inout] array of `nnz` integers containing the unsorted map indices, can be `NULL`.

    - temp_buffer – [in] temporary storage buffer allocated by the user, size is returned by rocsparse_csrsort_buffer_size().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m`, `n` or `nnz` is invalid.

    - rocsparse_status_invalid_pointer – `descr`, `csr_row_ptr`, `csr_col_ind` or `temp_buffer` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

    - rocsparse_status_not_implemented – rocsparse_matrix_type != rocsparse_matrix_type_general.

### rocsparse_cscsort_buffer_size()

rocsparse_status rocsparse_cscsort_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const rocsparse_int *csc_col_ptr, const rocsparse_int *csc_row_ind, size_t *buffer_size)

  Sort a sparse CSC matrix.

  `rocsparse_cscsort_buffer_size` returns the size of the temporary storage buffer required by rocsparse_cscsort(). The temporary storage buffer must be allocated by the user.

  Note

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

  Note

  This routine supports execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows of the sparse CSC matrix.

    - n – [in] number of columns of the sparse CSC matrix.

    - nnz – [in] number of non-zero entries of the sparse CSC matrix.

    - csc_col_ptr – [in] array of `n+1` elements that point to the start of every column of the sparse CSC matrix.

    - csc_row_ind – [in] array of `nnz` elements containing the row indices of the sparse CSC matrix.

    - buffer_size – [out] number of bytes of the temporary storage buffer required by rocsparse_cscsort().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m`, `n` or `nnz` is invalid.

    - rocsparse_status_invalid_pointer – `csc_col_ptr`, `csc_row_ind` or `buffer_size` pointer is invalid.

### rocsparse_cscsort()

rocsparse_status rocsparse_cscsort(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const rocsparse_mat_descr descr, const rocsparse_int *csc_col_ptr, rocsparse_int *csc_row_ind, rocsparse_int *perm, void *temp_buffer)

  Sort a sparse CSC matrix.

  `rocsparse_cscsort` sorts a matrix in CSC format. The sorted permutation vector `perm` can be used to obtain sorted `csc_val` array. In this case, `perm` must be initialized as the identity permutation, see rocsparse_create_identity_permutation().

  `rocsparse_cscsort` requires extra temporary storage buffer that has to be allocated by the user. Storage buffer size can be determined by rocsparse_cscsort_buffer_size().

  Example

    The following example sorts a \(3 \times 3\) CSC matrix.

        //     1 2 3
        // A = 4 5 6
        //     7 8 9
        rocsparse_int m   = 3;
        rocsparse_int n   = 3;
        rocsparse_int nnz = 9;

        csc_col_ptr[m + 1] = {0, 3, 6, 9};                // device memory
        csc_row_ind[nnz]   = {2, 0, 1, 0, 1, 2, 0, 2, 1}; // device memory
        csc_val[nnz]       = {7, 1, 4, 2, 5, 8, 3, 9, 6}; // device memory

        // Create permutation vector perm as the identity map
        rocsparse_int* perm;
        hipMalloc((void**)&perm, sizeof(rocsparse_int) * nnz);
        rocsparse_create_identity_permutation(handle, nnz, perm);

        // Allocate temporary buffer
        size_t buffer_size;
        void* temp_buffer;
        rocsparse_cscsort_buffer_size(handle, m, n, nnz, csc_col_ptr, csc_row_ind, &buffer_size);
        hipMalloc(&temp_buffer, buffer_size);

        // Sort the CSC matrix
        rocsparse_cscsort(handle, m, n, nnz, descr, csc_col_ptr, csc_row_ind, perm, temp_buffer);

        // Gather sorted csc_val array
        float* csc_val_sorted;
        hipMalloc((void**)&csc_val_sorted, sizeof(float) * nnz);
        rocsparse_sgthr(handle, nnz, csc_val, csc_val_sorted, perm, rocsparse_index_base_zero);

        // Clean up
        hipFree(temp_buffer);
        hipFree(perm);
        hipFree(csc_val);

  Note

  `perm` can be `NULL` if a sorted permutation vector is not required.

  Note

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

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows of the sparse CSC matrix.

    - n – [in] number of columns of the sparse CSC matrix.

    - nnz – [in] number of non-zero entries of the sparse CSC matrix.

    - descr – [in] descriptor of the sparse CSC matrix. Currently, only rocsparse_matrix_type_general is supported.

    - csc_col_ptr – [in] array of `n+1` elements that point to the start of every column of the sparse CSC matrix.

    - csc_row_ind – [inout] array of `nnz` elements containing the row indices of the sparse CSC matrix.

    - perm – [inout] array of `nnz` integers containing the unsorted map indices, can be `NULL`.

    - temp_buffer – [in] temporary storage buffer allocated by the user, size is returned by rocsparse_cscsort_buffer_size().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m`, `n` or `nnz` is invalid.

    - rocsparse_status_invalid_pointer – `descr`, `csc_col_ptr`, `csc_row_ind` or `temp_buffer` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

    - rocsparse_status_not_implemented – rocsparse_matrix_type != rocsparse_matrix_type_general.

### rocsparse_coosort_buffer_size()

rocsparse_status rocsparse_coosort_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const rocsparse_int *coo_row_ind, const rocsparse_int *coo_col_ind, size_t *buffer_size)

  Sort a sparse COO matrix.

  `coosort_buffer_size` returns the size of the temporary storage buffer that is required by rocsparse_coosort_by_row() and rocsparse_coosort_by_column(). The temporary storage buffer has to be allocated by the user.

  Note

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

  Note

  This routine supports execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows of the sparse COO matrix.

    - n – [in] number of columns of the sparse COO matrix.

    - nnz – [in] number of non-zero entries of the sparse COO matrix.

    - coo_row_ind – [in] array of `nnz` elements containing the row indices of the sparse COO matrix.

    - coo_col_ind – [in] array of `nnz` elements containing the column indices of the sparse COO matrix.

    - buffer_size – [out] number of bytes of the temporary storage buffer required by rocsparse_coosort_by_row() and rocsparse_coosort_by_column().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m`, `n` or `nnz` is invalid.

    - rocsparse_status_invalid_pointer – `coo_row_ind`, `coo_col_ind` or `buffer_size` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

### rocsparse_coosort_by_row()

rocsparse_status rocsparse_coosort_by_row(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, rocsparse_int *coo_row_ind, rocsparse_int *coo_col_ind, rocsparse_int *perm, void *temp_buffer)

  Sort a sparse COO matrix by row.

  `rocsparse_coosort_by_row` sorts a matrix in COO format by row. The sorted permutation vector `perm` can be used to obtain sorted `coo_val` array. In this case, `perm` must be initialized as the identity permutation, see rocsparse_create_identity_permutation().

  `rocsparse_coosort_by_row` requires extra temporary storage buffer that has to be allocated by the user. Storage buffer size can be determined by rocsparse_coosort_buffer_size().

  Example

    The following example sorts a \(3 \times 3\) COO matrix by row indices.

        //     1 2 3
        // A = 4 5 6
        //     7 8 9
        rocsparse_int m   = 3;
        rocsparse_int n   = 3;
        rocsparse_int nnz = 9;

        coo_row_ind[nnz] = {0, 1, 2, 0, 1, 2, 0, 1, 2}; // device memory
        coo_col_ind[nnz] = {0, 0, 0, 1, 1, 1, 2, 2, 2}; // device memory
        coo_val[nnz]     = {1, 4, 7, 2, 5, 8, 3, 6, 9}; // device memory

        // Create permutation vector perm as the identity map
        rocsparse_int* perm;
        hipMalloc((void**)&perm, sizeof(rocsparse_int) * nnz);
        rocsparse_create_identity_permutation(handle, nnz, perm);

        // Allocate temporary buffer
        size_t buffer_size;
        void* temp_buffer;
        rocsparse_coosort_buffer_size(handle,
                                      m,
                                      n,
                                      nnz,
                                      coo_row_ind,
                                      coo_col_ind,
                                      &buffer_size);
        hipMalloc(&temp_buffer, buffer_size);

        // Sort the COO matrix
        rocsparse_coosort_by_row(handle,
                                 m,
                                 n,
                                 nnz,
                                 coo_row_ind,
                                 coo_col_ind,
                                 perm,
                                 temp_buffer);

        // Gather sorted coo_val array
        float* coo_val_sorted;
        hipMalloc((void**)&coo_val_sorted, sizeof(float) * nnz);
        rocsparse_sgthr(handle, nnz, coo_val, coo_val_sorted, perm, rocsparse_index_base_zero);

        // Clean up
        hipFree(temp_buffer);
        hipFree(perm);
        hipFree(coo_val);

  Note

  `perm` can be `NULL` if a sorted permutation vector is not required.

  Note

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

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows of the sparse COO matrix.

    - n – [in] number of columns of the sparse COO matrix.

    - nnz – [in] number of non-zero entries of the sparse COO matrix.

    - coo_row_ind – [inout] array of `nnz` elements containing the row indices of the sparse COO matrix.

    - coo_col_ind – [inout] array of `nnz` elements containing the column indices of the sparse COO matrix.

    - perm – [inout] array of `nnz` integers containing the unsorted map indices, can be `NULL`.

    - temp_buffer – [in] temporary storage buffer allocated by the user, size is returned by rocsparse_coosort_buffer_size().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m`, `n` or `nnz` is invalid.

    - rocsparse_status_invalid_pointer – `coo_row_ind`, `coo_col_ind` or `temp_buffer` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

### rocsparse_coosort_by_column()

rocsparse_status rocsparse_coosort_by_column(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, rocsparse_int *coo_row_ind, rocsparse_int *coo_col_ind, rocsparse_int *perm, void *temp_buffer)

  Sort a sparse COO matrix by column.

  `rocsparse_coosort_by_column` sorts a matrix in COO format by column. The sorted permutation vector `perm` can be used to obtain sorted `coo_val` array. In this case, `perm` must be initialized as the identity permutation, see rocsparse_create_identity_permutation().

  `rocsparse_coosort_by_column` requires extra temporary storage buffer that has to be allocated by the user. Storage buffer size can be determined by rocsparse_coosort_buffer_size().

  Example

    The following example sorts a \(3 \times 3\) COO matrix by column indices.

        //     1 2 3
        // A = 4 5 6
        //     7 8 9
        rocsparse_int m   = 3;
        rocsparse_int n   = 3;
        rocsparse_int nnz = 9;

        coo_row_ind[nnz] = {0, 0, 0, 1, 1, 1, 2, 2, 2}; // device memory
        coo_col_ind[nnz] = {0, 1, 2, 0, 1, 2, 0, 1, 2}; // device memory
        coo_val[nnz]     = {1, 2, 3, 4, 5, 6, 7, 8, 9}; // device memory

        // Create permutation vector perm as the identity map
        rocsparse_int* perm;
        hipMalloc((void**)&perm, sizeof(rocsparse_int) * nnz);
        rocsparse_create_identity_permutation(handle, nnz, perm);

        // Allocate temporary buffer
        size_t buffer_size;
        void* temp_buffer;
        rocsparse_coosort_buffer_size(handle,
                                      m,
                                      n,
                                      nnz,
                                      coo_row_ind,
                                      coo_col_ind,
                                      &buffer_size);
        hipMalloc(&temp_buffer, buffer_size);

        // Sort the COO matrix
        rocsparse_coosort_by_column(handle,
                                    m,
                                    n,
                                    nnz,
                                    coo_row_ind,
                                    coo_col_ind,
                                    perm,
                                    temp_buffer);

        // Gather sorted coo_val array
        float* coo_val_sorted;
        hipMalloc((void**)&coo_val_sorted, sizeof(float) * nnz);
        rocsparse_sgthr(handle, nnz, coo_val, coo_val_sorted, perm, rocsparse_index_base_zero);

        // Clean up
        hipFree(temp_buffer);
        hipFree(perm);
        hipFree(coo_val);

  Note

  `perm` can be `NULL` if a sorted permutation vector is not required.

  Note

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

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows of the sparse COO matrix.

    - n – [in] number of columns of the sparse COO matrix.

    - nnz – [in] number of non-zero entries of the sparse COO matrix.

    - coo_row_ind – [inout] array of `nnz` elements containing the row indices of the sparse COO matrix.

    - coo_col_ind – [inout] array of `nnz` elements containing the column indices of the sparse COO matrix.

    - perm – [inout] array of `nnz` integers containing the unsorted map indices, can be `NULL`.

    - temp_buffer – [in] temporary storage buffer allocated by the user, size is returned by rocsparse_coosort_buffer_size().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m`, `n` or `nnz` is invalid.

    - rocsparse_status_invalid_pointer – `coo_row_ind`, `coo_col_ind` or `temp_buffer` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

### rocsparse_nnz_compress()

rocsparse_status rocsparse_snnz_compress(rocsparse_handle handle, rocsparse_int m, const rocsparse_mat_descr descr_A, const float *csr_val_A, const rocsparse_int *csr_row_ptr_A, rocsparse_int *nnz_per_row, rocsparse_int *nnz_C, float tol)

rocsparse_status rocsparse_dnnz_compress(rocsparse_handle handle, rocsparse_int m, const rocsparse_mat_descr descr_A, const double *csr_val_A, const rocsparse_int *csr_row_ptr_A, rocsparse_int *nnz_per_row, rocsparse_int *nnz_C, double tol)

rocsparse_status rocsparse_cnnz_compress(rocsparse_handle handle, rocsparse_int m, const rocsparse_mat_descr descr_A, const rocsparse_float_complex *csr_val_A, const rocsparse_int *csr_row_ptr_A, rocsparse_int *nnz_per_row, rocsparse_int *nnz_C, rocsparse_float_complex tol)

rocsparse_status rocsparse_znnz_compress(rocsparse_handle handle, rocsparse_int m, const rocsparse_mat_descr descr_A, const rocsparse_double_complex *csr_val_A, const rocsparse_int *csr_row_ptr_A, rocsparse_int *nnz_per_row, rocsparse_int *nnz_C, rocsparse_double_complex tol)

  Given a sparse CSR matrix and a non-negative tolerance, this function computes how many entries would be left in each row of the matrix if elements less than the tolerance were removed. It also computes the total number of remaining elements in the matrix.

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows of the sparse CSR matrix.

    - descr_A – [in] the descriptor of the sparse CSR matrix.

    - csr_val_A – [in] array of `nnz_A` elements of the sparse CSR matrix.

    - csr_row_ptr_A – [in] array of `m+1` elements that point to the start of every row of the uncompressed sparse CSR matrix.

    - nnz_per_row – [out] array of length `m` containing the number of entries that will be kept per row in the final compressed CSR matrix.

    - nnz_C – [out] number of elements in the column indices and values arrays of the compressed sparse CSR matrix. Can be either host or device pointer.

    - tol – [in] the non-negative tolerance used for compression. If `tol` is complex then only the magnitude of the real part is used. Entries in the input uncompressed CSR array that are below the tolerance are removed in output compressed CSR matrix.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m` or `n` is invalid.

    - rocsparse_status_invalid_value – `tol` is invalid.

    - rocsparse_status_invalid_pointer – `csr_val_A` or `csr_row_ptr_A` or `nnz_per_row` or `nnz_C` pointer is invalid.

### rocsparse_nnz()

rocsparse_status rocsparse_snnz(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const float *A, rocsparse_int ld, rocsparse_int *nnz_per_row_columns, rocsparse_int *nnz_total_dev_host_ptr)

rocsparse_status rocsparse_dnnz(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const double *A, rocsparse_int ld, rocsparse_int *nnz_per_row_columns, rocsparse_int *nnz_total_dev_host_ptr)

rocsparse_status rocsparse_cnnz(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const rocsparse_float_complex *A, rocsparse_int ld, rocsparse_int *nnz_per_row_columns, rocsparse_int *nnz_total_dev_host_ptr)

rocsparse_status rocsparse_znnz(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const rocsparse_double_complex *A, rocsparse_int ld, rocsparse_int *nnz_per_row_columns, rocsparse_int *nnz_total_dev_host_ptr)

  This function computes the number of nonzero elements per row or column and the total number of nonzero elements in a dense matrix.

  The routine does support asynchronous execution if the pointer mode is set to device.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - dir – [in] direction that specified whether to count nonzero elements by rocsparse_direction_row or by rocsparse_direction_row.

    - m – [in] number of rows of the dense matrix `A`.

    - n – [in] number of columns of the dense matrix `A`.

    - descr – [in] the descriptor of the dense matrix `A`.

    - A – [in] array of dimensions (`ld`, `n`)

    - ld – [in] leading dimension of dense array `A`.

    - nnz_per_row_columns – [out] array of size `m` or `n` containing the number of nonzero elements per row or column, respectively.

    - nnz_total_dev_host_ptr – [out] total number of nonzero elements in device or host memory.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m` or `n` or `ld` is invalid.

    - rocsparse_status_invalid_pointer – `A` or `nnz_per_row_columns` or `nnz_total_dev_host_ptr` pointer is invalid.

### rocsparse_dense2csr()

rocsparse_status rocsparse_sdense2csr(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const float *A, rocsparse_int ld, const rocsparse_int *nnz_per_rows, float *csr_val, rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind)

rocsparse_status rocsparse_ddense2csr(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const double *A, rocsparse_int ld, const rocsparse_int *nnz_per_rows, double *csr_val, rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind)

rocsparse_status rocsparse_cdense2csr(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const rocsparse_float_complex *A, rocsparse_int ld, const rocsparse_int *nnz_per_rows, rocsparse_float_complex *csr_val, rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind)

rocsparse_status rocsparse_zdense2csr(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const rocsparse_double_complex *A, rocsparse_int ld, const rocsparse_int *nnz_per_rows, rocsparse_double_complex *csr_val, rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind)

  This function converts the matrix A in dense format into a sparse matrix in CSR format. All the parameters are assumed to have been pre-allocated by the user and the arrays are filled in based on nnz_per_row, which can be pre-computed with rocsparse_xnnz().

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows of the dense matrix `A`.

    - n – [in] number of columns of the dense matrix `A`.

    - descr – [in] the descriptor of the dense matrix `A`, the supported matrix type is rocsparse_matrix_type_general and also any valid value of the rocsparse_index_base.

    - A – [in] array of dimensions (`ld`, `n`)

    - ld – [in] leading dimension of dense array `A`.

    - nnz_per_rows – [in] array of size `n` containing the number of non-zero elements per row.

    - csr_val – [out] array of nnz ( = `csr_row_ptr`[m] - `csr_row_ptr`[0] ) nonzero elements of matrix `A`.

    - csr_row_ptr – [out] integer array of m+1 elements that contains the start of every row and the end of the last row plus one.

    - csr_col_ind – [out] integer array of nnz ( = `csr_row_ptr`[m] - csr_row_ptr[0] ) column indices of the non-zero elements of matrix `A`.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m` or `n` or `ld` is invalid.

    - rocsparse_status_invalid_pointer – `A` or `nnz_per_rows` or `csr_val` `csr_row_ptr` or `csr_col_ind` pointer is invalid.

### rocsparse_dense2csc()

rocsparse_status rocsparse_sdense2csc(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const float *A, rocsparse_int ld, const rocsparse_int *nnz_per_columns, float *csc_val, rocsparse_int *csc_col_ptr, rocsparse_int *csc_row_ind)

rocsparse_status rocsparse_ddense2csc(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const double *A, rocsparse_int ld, const rocsparse_int *nnz_per_columns, double *csc_val, rocsparse_int *csc_col_ptr, rocsparse_int *csc_row_ind)

rocsparse_status rocsparse_cdense2csc(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const rocsparse_float_complex *A, rocsparse_int ld, const rocsparse_int *nnz_per_columns, rocsparse_float_complex *csc_val, rocsparse_int *csc_col_ptr, rocsparse_int *csc_row_ind)

rocsparse_status rocsparse_zdense2csc(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const rocsparse_double_complex *A, rocsparse_int ld, const rocsparse_int *nnz_per_columns, rocsparse_double_complex *csc_val, rocsparse_int *csc_col_ptr, rocsparse_int *csc_row_ind)

  This function converts the matrix A in dense format into a sparse matrix in CSC format. All the parameters are assumed to have been pre-allocated by the user and the arrays are filled in based on nnz_per_columns, which can be pre-computed with rocsparse_xnnz().

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows of the dense matrix `A`.

    - n – [in] number of columns of the dense matrix `A`.

    - descr – [in] the descriptor of the dense matrix `A`, the supported matrix type is rocsparse_matrix_type_general and also any valid value of the rocsparse_index_base.

    - A – [in] array of dimensions (`ld`, `n`)

    - ld – [in] leading dimension of dense array `A`.

    - nnz_per_columns – [in] array of size `n` containing the number of non-zero elements per column.

    - csc_val – [out] array of nnz ( = `csc_col_ptr`[m] - `csc_col_ptr`[0] ) nonzero elements of matrix `A`.

    - csc_col_ptr – [out] integer array of m+1 elements that contains the start of every column and the end of the last column plus one.

    - csc_row_ind – [out] integer array of nnz ( = `csc_col_ptr`[m] - csc_col_ptr[0] ) column indices of the non-zero elements of matrix `A`.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m` or `n` or `ld` is invalid.

    - rocsparse_status_invalid_pointer – `A` or `nnz_per_columns` or `csc_val` `csc_col_ptr` or `csc_row_ind` pointer is invalid.

### rocsparse_dense2coo()

rocsparse_status rocsparse_sdense2coo(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const float *A, rocsparse_int ld, const rocsparse_int *nnz_per_rows, float *coo_val, rocsparse_int *coo_row_ind, rocsparse_int *coo_col_ind)

rocsparse_status rocsparse_ddense2coo(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const double *A, rocsparse_int ld, const rocsparse_int *nnz_per_rows, double *coo_val, rocsparse_int *coo_row_ind, rocsparse_int *coo_col_ind)

rocsparse_status rocsparse_cdense2coo(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const rocsparse_float_complex *A, rocsparse_int ld, const rocsparse_int *nnz_per_rows, rocsparse_float_complex *coo_val, rocsparse_int *coo_row_ind, rocsparse_int *coo_col_ind)

rocsparse_status rocsparse_zdense2coo(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const rocsparse_double_complex *A, rocsparse_int ld, const rocsparse_int *nnz_per_rows, rocsparse_double_complex *coo_val, rocsparse_int *coo_row_ind, rocsparse_int *coo_col_ind)

  This function converts the matrix A in dense format into a sparse matrix in COO format. All the parameters are assumed to have been pre-allocated by the user and the arrays are filled in based on nnz_per_rows, which can be pre-computed with rocsparse_xnnz().

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows of the dense matrix `A`.

    - n – [in] number of columns of the dense matrix `A`.

    - descr – [in] the descriptor of the dense matrix `A`, the supported matrix type is rocsparse_matrix_type_general and also any valid value of the rocsparse_index_base.

    - A – [in] array of dimensions (`ld`, `n`)

    - ld – [in] leading dimension of dense array `A`.

    - nnz_per_rows – [in] array of size `n` containing the number of non-zero elements per row.

    - coo_val – [out] array of nnz nonzero elements of matrix `A`.

    - coo_row_ind – [out] integer array of nnz row indices of the non-zero elements of matrix `A`.

    - coo_col_ind – [out] integer array of nnz column indices of the non-zero elements of matrix `A`.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m` or `n` or `ld` is invalid.

    - rocsparse_status_invalid_pointer – `A` or `nnz_per_rows` or `coo_val` `coo_col_ind` or `coo_row_ind` pointer is invalid.

### rocsparse_csr2dense()

rocsparse_status rocsparse_scsr2dense(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const float *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, float *A, rocsparse_int ld)

rocsparse_status rocsparse_dcsr2dense(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const double *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, double *A, rocsparse_int ld)

rocsparse_status rocsparse_ccsr2dense(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const rocsparse_float_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_float_complex *A, rocsparse_int ld)

rocsparse_status rocsparse_zcsr2dense(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const rocsparse_double_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_double_complex *A, rocsparse_int ld)

  This function converts the sparse matrix in CSR format into a dense matrix.

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows of the dense matrix `A`.

    - n – [in] number of columns of the dense matrix `A`.

    - descr – [in] the descriptor of the dense matrix `A`, the supported matrix type is rocsparse_matrix_type_general and also any valid value of the rocsparse_index_base.

    - csr_val – [in] array of nnz ( = `csr_row_ptr`[m] - `csr_row_ptr`[0] ) nonzero elements of matrix `A`.

    - csr_row_ptr – [in] integer array of m+1 elements that contains the start of every row and the end of the last row plus one.

    - csr_col_ind – [in] integer array of nnz ( = `csr_row_ptr`[m] - csr_row_ptr[0] ) column indices of the non-zero elements of matrix `A`.

    - A – [out] array of dimensions (`ld`, `n`)

    - ld – [out] leading dimension of dense array `A`.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m` or `n` or `ld` is invalid.

    - rocsparse_status_invalid_pointer – `A` or `csr_val` `csr_row_ptr` or `csr_col_ind` pointer is invalid.

### rocsparse_csc2dense()

rocsparse_status rocsparse_scsc2dense(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const float *csc_val, const rocsparse_int *csc_col_ptr, const rocsparse_int *csc_row_ind, float *A, rocsparse_int ld)

rocsparse_status rocsparse_dcsc2dense(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const double *csc_val, const rocsparse_int *csc_col_ptr, const rocsparse_int *csc_row_ind, double *A, rocsparse_int ld)

rocsparse_status rocsparse_ccsc2dense(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const rocsparse_float_complex *csc_val, const rocsparse_int *csc_col_ptr, const rocsparse_int *csc_row_ind, rocsparse_float_complex *A, rocsparse_int ld)

rocsparse_status rocsparse_zcsc2dense(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const rocsparse_double_complex *csc_val, const rocsparse_int *csc_col_ptr, const rocsparse_int *csc_row_ind, rocsparse_double_complex *A, rocsparse_int ld)

  This function converts the sparse matrix in CSC format into a dense matrix.

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows of the dense matrix `A`.

    - n – [in] number of columns of the dense matrix `A`.

    - descr – [in] the descriptor of the dense matrix `A`, the supported matrix type is rocsparse_matrix_type_general and also any valid value of the rocsparse_index_base.

    - csc_val – [in] array of nnz ( = `csc_col_ptr`[m] - `csc_col_ptr`[0] ) nonzero elements of matrix `A`.

    - csc_col_ptr – [in] integer array of m+1 elements that contains the start of every row and the end of the last row plus one.

    - csc_row_ind – [in] integer array of nnz ( = `csc_col_ptr`[m] - csc_col_ptr[0] ) column indices of the non-zero elements of matrix `A`.

    - A – [out] array of dimensions (`ld`, `n`)

    - ld – [out] leading dimension of dense array `A`.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m` or `n` or `ld` is invalid.

    - rocsparse_status_invalid_pointer – `A` or `csc_val` `csc_col_ptr` or `csc_row_ind` pointer is invalid.

### rocsparse_coo2dense()

rocsparse_status rocsparse_scoo2dense(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const rocsparse_mat_descr descr, const float *coo_val, const rocsparse_int *coo_row_ind, const rocsparse_int *coo_col_ind, float *A, rocsparse_int ld)

rocsparse_status rocsparse_dcoo2dense(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const rocsparse_mat_descr descr, const double *coo_val, const rocsparse_int *coo_row_ind, const rocsparse_int *coo_col_ind, double *A, rocsparse_int ld)

rocsparse_status rocsparse_ccoo2dense(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const rocsparse_mat_descr descr, const rocsparse_float_complex *coo_val, const rocsparse_int *coo_row_ind, const rocsparse_int *coo_col_ind, rocsparse_float_complex *A, rocsparse_int ld)

rocsparse_status rocsparse_zcoo2dense(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const rocsparse_mat_descr descr, const rocsparse_double_complex *coo_val, const rocsparse_int *coo_row_ind, const rocsparse_int *coo_col_ind, rocsparse_double_complex *A, rocsparse_int ld)

  This function converts the sparse matrix in COO format into a dense matrix.

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows of the dense matrix `A`.

    - n – [in] number of columns of the dense matrix `A`.

    - nnz – [in] number of non-zero entries of the sparse COO matrix.

    - descr – [in] the descriptor of the dense matrix `A`, the supported matrix type is rocsparse_matrix_type_general and also any valid value of the rocsparse_index_base.

    - coo_val – [in] array of nnz nonzero elements of matrix `A`.

    - coo_row_ind – [in] integer array of nnz row indices of the non-zero elements of matrix `A`.

    - coo_col_ind – [in] integer array of nnz column indices of the non-zero elements of matrix `A`.

    - A – [out] array of dimensions (`ld`, `n`)

    - ld – [out] leading dimension of dense array `A`.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m` or `n` or `nnz` or `ld` is invalid.

    - rocsparse_status_invalid_pointer – `A` or `coo_val` `coo_col_ind` or `coo_row_ind` pointer is invalid.

### rocsparse_prune_dense2csr_buffer_size()

rocsparse_status rocsparse_sprune_dense2csr_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const float *A, rocsparse_int lda, const float *threshold, const rocsparse_mat_descr descr, const float *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, size_t *buffer_size)

rocsparse_status rocsparse_dprune_dense2csr_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const double *A, rocsparse_int lda, const double *threshold, const rocsparse_mat_descr descr, const double *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, size_t *buffer_size)

  This function computes the the size of the user allocated temporary storage buffer used when converting and pruning a dense matrix to a CSR matrix.

  `rocsparse_prune_dense2csr_buffer_size` returns the size of the temporary storage buffer that is required by rocsparse_sprune_dense2csr_nnz(), rocsparse_dprune_dense2csr_nnz(), rocsparse_sprune_dense2csr(), and rocsparse_dprune_dense2csr(). The temporary storage buffer must be allocated by the user.

  Note

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

  Note

  This routine supports execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows of the dense matrix `A`.

    - n – [in] number of columns of the dense matrix `A`.

    - A – [in] array of dimensions (`lda`, `n`)

    - lda – [in] leading dimension of dense array `A`.

    - threshold – [in] pointer to the pruning non-negative threshold which can exist in either host or device memory.

    - descr – [in] the descriptor of the dense matrix `A`, the supported matrix type is rocsparse_matrix_type_general and also any valid value of the rocsparse_index_base.

    - csr_val – [in] array of nnz ( = `csr_row_ptr`[m] - `csr_row_ptr`[0] ) nonzero elements of matrix `A`.

    - csr_row_ptr – [in] integer array of `m+1` elements that contains the start of every row and the end of the last row plus one.

    - csr_col_ind – [in] integer array of nnz ( = `csr_row_ptr`[m] - csr_row_ptr[0] ) column indices of the non-zero elements of matrix `A`.

    - buffer_size – [out] number of bytes of the temporary storage buffer required by rocsparse_sprune_dense2csr_nnz(), rocsparse_dprune_dense2csr_nnz(), rocsparse_sprune_dense2csr() and rocsparse_dprune_dense2csr().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_pointer – `buffer_size` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

### rocsparse_prune_dense2csr_nnz()

rocsparse_status rocsparse_sprune_dense2csr_nnz(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const float *A, rocsparse_int lda, const float *threshold, const rocsparse_mat_descr descr, rocsparse_int *csr_row_ptr, rocsparse_int *nnz_total_dev_host_ptr, void *temp_buffer)

rocsparse_status rocsparse_dprune_dense2csr_nnz(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const double *A, rocsparse_int lda, const double *threshold, const rocsparse_mat_descr descr, rocsparse_int *csr_row_ptr, rocsparse_int *nnz_total_dev_host_ptr, void *temp_buffer)

  This function computes the number of nonzero elements per row and the total number of nonzero elements in a dense matrix once elements less than the threshold are pruned from the matrix.

  The routine does support asynchronous execution if the pointer mode is set to device.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows of the dense matrix `A`.

    - n – [in] number of columns of the dense matrix `A`.

    - A – [in] array of dimensions (`lda`, `n`)

    - lda – [in] leading dimension of dense array `A`.

    - threshold – [in] pointer to the pruning non-negative threshold which can exist in either host or device memory.

    - descr – [in] the descriptor of the dense matrix `A`.

    - csr_row_ptr – [out] integer array of `m+1` elements that contains the start of every row and the end of the last row plus one.

    - nnz_total_dev_host_ptr – [out] total number of nonzero elements in device or host memory.

    - temp_buffer – [out] buffer allocated by the user whose size is determined by calling rocsparse_xprune_dense2csr_buffer_size().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m` or `n` or `lda` is invalid.

    - rocsparse_status_invalid_pointer – `A` or `threshold` or `descr` or `csr_row_ptr` or `nnz_total_dev_host_ptr` or `temp_buffer` pointer is invalid.

### rocsparse_prune_dense2csr()

rocsparse_status rocsparse_sprune_dense2csr(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const float *A, rocsparse_int lda, const float *threshold, const rocsparse_mat_descr descr, float *csr_val, const rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind, void *temp_buffer)

rocsparse_status rocsparse_dprune_dense2csr(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const double *A, rocsparse_int lda, const double *threshold, const rocsparse_mat_descr descr, double *csr_val, const rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind, void *temp_buffer)

  This function converts the matrix A in dense format into a sparse matrix in CSR format while pruning values that are less than the threshold. All the parameters are assumed to have been pre-allocated by the user.

  The user first allocates `csr_row_ptr` to have `m+1` elements and then calls rocsparse_xprune_dense2csr_nnz() which fills in the `csr_row_ptr` array and stores the number of elements that are larger than the pruning threshold in `nnz_total_dev_host_ptr`. The user then allocates `csr_col_ind` and `csr_val` to have size `nnz_total_dev_host_ptr` and completes the conversion by calling rocsparse_xprune_dense2csr(). A temporary storage buffer is used by both rocsparse_xprune_dense2csr_nnz() and rocsparse_xprune_dense2csr() and must be allocated by the user and whose size is determined by rocsparse_xprune_dense2csr_buffer_size().

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows of the dense matrix `A`.

    - n – [in] number of columns of the dense matrix `A`.

    - A – [in] array of dimensions (`lda`, `n`)

    - lda – [in] leading dimension of dense array `A`.

    - threshold – [in] pointer to the non-negative pruning threshold which can exist in either host or device memory.

    - descr – [in] the descriptor of the dense matrix `A`, the supported matrix type is rocsparse_matrix_type_general and also any valid value of the rocsparse_index_base.

    - csr_val – [out] array of nnz ( = `csr_row_ptr`[m] - `csr_row_ptr`[0] ) nonzero elements of matrix `A`.

    - csr_row_ptr – [in] integer array of `m+1` elements that contains the start of every row and the end of the last row plus one.

    - csr_col_ind – [out] integer array of nnz ( = `csr_row_ptr`[m] - csr_row_ptr[0] ) column indices of the non-zero elements of matrix `A`.

    - temp_buffer – [in] temporary storage buffer allocated by the user, size is returned by rocsparse_xprune_dense2csr_buffer_size().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m` or `n` or `lda` is invalid.

    - rocsparse_status_invalid_pointer – `A` or `descr` or `threshold` or `csr_val` or `csr_row_ptr` or `csr_col_ind` or `temp_buffer` pointer is invalid.

### rocsparse_prune_csr2csr_buffer_size()

rocsparse_status rocsparse_sprune_csr2csr_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz_A, const rocsparse_mat_descr csr_descr_A, const float *csr_val_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, const float *threshold, const rocsparse_mat_descr csr_descr_C, const float *csr_val_C, const rocsparse_int *csr_row_ptr_C, const rocsparse_int *csr_col_ind_C, size_t *buffer_size)

rocsparse_status rocsparse_dprune_csr2csr_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz_A, const rocsparse_mat_descr csr_descr_A, const double *csr_val_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, const double *threshold, const rocsparse_mat_descr csr_descr_C, const double *csr_val_C, const rocsparse_int *csr_row_ptr_C, const rocsparse_int *csr_col_ind_C, size_t *buffer_size)

  Convert and prune sparse CSR matrix into a sparse CSR matrix.

  `rocsparse_prune_csr2csr_buffer_size` returns the size of the temporary buffer that is required by `rocsparse_sprune_csr2csr_nnz`, `rocsparse_dprune_csr2csr_nnz`, `rocsparse_sprune_csr2csr`, and `rocsparse_dprune_csr2csr`. The temporary storage buffer must be allocated by the user.

  Note

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

  Note

  This routine supports execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows in the sparse CSR matrix.

    - n – [in] number of columns in the sparse CSR matrix.

    - nnz_A – [in] number of non-zeros in the sparse CSR matrix A.

    - csr_descr_A – [in] descriptor of the sparse CSR matrix A. Currently, only rocsparse_matrix_type_general is supported.

    - csr_val_A – [in] array of `nnz_A` elements containing the values of the sparse CSR matrix A.

    - csr_row_ptr_A – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix A.

    - csr_col_ind_A – [in] array of `nnz_A` elements containing the column indices of the sparse CSR matrix A.

    - threshold – [in] pointer to the non-negative pruning threshold which can exist in either host or device memory.

    - csr_descr_C – [in] descriptor of the sparse CSR matrix C. Currently, only rocsparse_matrix_type_general is supported.

    - csr_val_C – [in] array of `nnz_C` elements containing the values of the sparse CSR matrix C.

    - csr_row_ptr_C – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix C.

    - csr_col_ind_C – [in] array of `nnz_C` elements containing the column indices of the sparse CSR matrix C.

    - buffer_size – [out] number of bytes of the temporary storage buffer required by `rocsparse_sprune_csr2csr_nnz`, `rocsparse_dprune_csr2csr_nnz`, `rocsparse_sprune_csr2csr`, and `rocsparse_dprune_csr2csr`.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_pointer – `buffer_size` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

### rocsparse_prune_csr2csr_nnz()

rocsparse_status rocsparse_sprune_csr2csr_nnz(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz_A, const rocsparse_mat_descr csr_descr_A, const float *csr_val_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, const float *threshold, const rocsparse_mat_descr csr_descr_C, rocsparse_int *csr_row_ptr_C, rocsparse_int *nnz_total_dev_host_ptr, void *temp_buffer)

rocsparse_status rocsparse_dprune_csr2csr_nnz(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz_A, const rocsparse_mat_descr csr_descr_A, const double *csr_val_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, const double *threshold, const rocsparse_mat_descr csr_descr_C, rocsparse_int *csr_row_ptr_C, rocsparse_int *nnz_total_dev_host_ptr, void *temp_buffer)

  Convert and prune sparse CSR matrix into a sparse CSR matrix.

  `rocsparse_prune_csr2csr_nnz` computes the number of nonzero elements per row and the total number of nonzero elements in a sparse CSR matrix once elements less than the threshold are pruned from the matrix.

  Note

  The routine does support asynchronous execution if the pointer mode is set to device.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows in the sparse CSR matrix.

    - n – [in] number of columns in the sparse CSR matrix.

    - nnz_A – [in] number of non-zeros in the sparse CSR matrix A.

    - csr_descr_A – [in] descriptor of the sparse CSR matrix A. Currently, only rocsparse_matrix_type_general is supported.

    - csr_val_A – [in] array of `nnz_A` elements containing the values of the sparse CSR matrix A.

    - csr_row_ptr_A – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix A.

    - csr_col_ind_A – [in] array of `nnz_A` elements containing the column indices of the sparse CSR matrix A.

    - threshold – [in] pointer to the non-negative pruning threshold which can exist in either host or device memory.

    - csr_descr_C – [in] descriptor of the sparse CSR matrix C. Currently, only rocsparse_matrix_type_general is supported.

    - csr_row_ptr_C – [out] array of `m+1` elements that point to the start of every row of the sparse CSR matrix C.

    - nnz_total_dev_host_ptr – [out] total number of nonzero elements in device or host memory.

    - temp_buffer – [out] buffer allocated by the user whose size is determined by calling `rocsparse_xprune_csr2csr_buffer_size()`.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m` or `n` or `nnz_A` is invalid.

    - rocsparse_status_invalid_pointer – `threshold` or `csr_descr_A` or `csr_descr_C` or `csr_val_A` or `csr_row_ptr_A` or `csr_col_ind_A` or `csr_row_ptr_C` or `nnz_total_dev_host_ptr` or `temp_buffer` pointer is invalid.

### rocsparse_prune_csr2csr()

rocsparse_status rocsparse_sprune_csr2csr(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz_A, const rocsparse_mat_descr csr_descr_A, const float *csr_val_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, const float *threshold, const rocsparse_mat_descr csr_descr_C, float *csr_val_C, const rocsparse_int *csr_row_ptr_C, rocsparse_int *csr_col_ind_C, void *temp_buffer)

rocsparse_status rocsparse_dprune_csr2csr(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz_A, const rocsparse_mat_descr csr_descr_A, const double *csr_val_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, const double *threshold, const rocsparse_mat_descr csr_descr_C, double *csr_val_C, const rocsparse_int *csr_row_ptr_C, rocsparse_int *csr_col_ind_C, void *temp_buffer)

  Convert and prune sparse CSR matrix into a sparse CSR matrix.

  This function converts the sparse CSR matrix A into a sparse CSR matrix C by pruning values in A that are less than the threshold. All the parameters are assumed to have been pre-allocated by the user. The user first calls rocsparse_xprune_csr2csr_buffer_size() to determine the size of the buffer used by rocsparse_xprune_csr2csr_nnz() and rocsparse_xprune_csr2csr() which the user then allocates. The user then allocates `csr_row_ptr_C` to have `m+1` elements and then calls rocsparse_xprune_csr2csr_nnz() which fills in the `csr_row_ptr_C` array stores then number of elements that are larger than the pruning threshold in `nnz_total_dev_host_ptr`. The user then calls rocsparse_xprune_csr2csr() to complete the conversion.

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows in the sparse CSR matrix.

    - n – [in] number of columns in the sparse CSR matrix.

    - nnz_A – [in] number of non-zeros in the sparse CSR matrix A.

    - csr_descr_A – [in] descriptor of the sparse CSR matrix A. Currently, only rocsparse_matrix_type_general is supported.

    - csr_val_A – [in] array of `nnz_A` elements containing the values of the sparse CSR matrix A.

    - csr_row_ptr_A – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix A.

    - csr_col_ind_A – [in] array of `nnz_A` elements containing the column indices of the sparse CSR matrix A.

    - threshold – [in] pointer to the non-negative pruning threshold which can exist in either host or device memory.

    - csr_descr_C – [in] descriptor of the sparse CSR matrix C. Currently, only rocsparse_matrix_type_general is supported.

    - csr_val_C – [out] array of `nnz_C` elements containing the values of the sparse CSR matrix C.

    - csr_row_ptr_C – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix C.

    - csr_col_ind_C – [out] array of `nnz_C` elements containing the column indices of the sparse CSR matrix C.

    - temp_buffer – [in] buffer allocated by the user whose size is determined by calling `rocsparse_xprune_csr2csr_buffer_size()`.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m` or `n` or `nnz_A` is invalid.

    - rocsparse_status_invalid_pointer – `threshold` or `csr_descr_A` or `csr_descr_C` or `csr_val_A` or `csr_row_ptr_A` or `csr_col_ind_A` or `csr_val_C` or `csr_row_ptr_C` or `csr_col_ind_C` or `temp_buffer` pointer is invalid.

### rocsparse_prune_dense2csr_by_percentage_buffer_size()

rocsparse_status rocsparse_sprune_dense2csr_by_percentage_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const float *A, rocsparse_int lda, float percentage, const rocsparse_mat_descr descr, const float *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, size_t *buffer_size)

rocsparse_status rocsparse_dprune_dense2csr_by_percentage_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const double *A, rocsparse_int lda, double percentage, const rocsparse_mat_descr descr, const double *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, size_t *buffer_size)

  This function computes the size of the user allocated temporary storage buffer used when converting and pruning by percentage a dense matrix to a CSR matrix.

  When converting and pruning a dense matrix A to a CSR matrix by percentage the following steps are performed. First the user calls `rocsparse_prune_dense2csr_by_percentage_buffer_size` which determines the size of the temporary storage buffer. Once determined, this buffer must be allocated by the user. Next the user allocates the csr_row_ptr array to have `m+1` elements and calls `rocsparse_prune_dense2csr_nnz_by_percentage`. Finally the user finishes the conversion by allocating the csr_col_ind and csr_val arrays (whos size is determined by the value at nnz_total_dev_host_ptr) and calling `rocsparse_prune_dense2csr_by_percentage`.

  The pruning by percentage works by first sorting the absolute values of the dense matrix `A`. We then determine a position in this sorted array by

  \[ pos = ceil(m*n*(percentage/100)) - 1 pos = min(pos, m*n-1) pos = max(pos, 0) threshold = sorted_A[pos] \]
  Once we have this threshold we prune values in the dense matrix `A` as in `rocsparse_prune_dense2csr`.

  Note

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

  Note

  This routine supports execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows of the dense matrix `A`.

    - n – [in] number of columns of the dense matrix `A`.

    - A – [in] array of dimensions (`lda`, `n`)

    - lda – [in] leading dimension of dense array `A`.

    - percentage – [in] percentage >= 0 and percentage <= 100.

    - descr – [in] the descriptor of the dense matrix `A`, the supported matrix type is rocsparse_matrix_type_general and also any valid value of the rocsparse_index_base.

    - csr_val – [in] array of nnz ( = `csr_row_ptr`[m] - `csr_row_ptr`[0] ) nonzero elements of matrix `A`.

    - csr_row_ptr – [in] integer array of `m+1` elements that contains the start of every row and the end of the last row plus one.

    - csr_col_ind – [in] integer array of nnz ( = `csr_row_ptr`[m] - csr_row_ptr[0] ) column indices of the non-zero elements of matrix `A`.

    - info – [in] prune information structure

    - buffer_size – [out] number of bytes of the temporary storage buffer required by rocsparse_sprune_dense2csr_nnz_by_percentage(), rocsparse_dprune_dense2csr_nnz_by_percentage(), rocsparse_sprune_dense2csr_by_percentage() and rocsparse_dprune_dense2csr_by_percentage().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_pointer – `buffer_size` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

### rocsparse_prune_dense2csr_nnz_by_percentage()

rocsparse_status rocsparse_sprune_dense2csr_nnz_by_percentage(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const float *A, rocsparse_int lda, float percentage, const rocsparse_mat_descr descr, rocsparse_int *csr_row_ptr, rocsparse_int *nnz_total_dev_host_ptr, rocsparse_mat_info info, void *temp_buffer)

rocsparse_status rocsparse_dprune_dense2csr_nnz_by_percentage(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const double *A, rocsparse_int lda, double percentage, const rocsparse_mat_descr descr, rocsparse_int *csr_row_ptr, rocsparse_int *nnz_total_dev_host_ptr, rocsparse_mat_info info, void *temp_buffer)

  This function computes the number of nonzero elements per row and the total number of nonzero elements in a dense matrix when converting and pruning by percentage a dense matrix to a CSR matrix.

  When converting and pruning a dense matrix A to a CSR matrix by percentage the following steps are performed. First the user calls `rocsparse_prune_dense2csr_by_percentage_buffer_size` which determines the size of the temporary storage buffer. Once determined, this buffer must be allocated by the user. Next the user allocates the csr_row_ptr array to have `m+1` elements and calls `rocsparse_prune_dense2csr_nnz_by_percentage`. Finally the user finishes the conversion by allocating the csr_col_ind and csr_val arrays (whos size is determined by the value at nnz_total_dev_host_ptr) and calling `rocsparse_prune_dense2csr_by_percentage`.

  The pruning by percentage works by first sorting the absolute values of the dense matrix `A`. We then determine a position in this sorted array by

  \[ pos = ceil(m*n*(percentage/100)) - 1 pos = min(pos, m*n-1) pos = max(pos, 0) threshold = sorted_A[pos] \]
  Once we have this threshold we prune values in the dense matrix `A` as in `rocsparse_prune_dense2csr`.

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows of the dense matrix `A`.

    - n – [in] number of columns of the dense matrix `A`.

    - A – [in] array of dimensions (`lda`, `n`)

    - lda – [in] leading dimension of dense array `A`.

    - percentage – [in] percentage >= 0 and percentage <= 100.

    - descr – [in] the descriptor of the dense matrix `A`.

    - csr_row_ptr – [out] integer array of `m+1` elements that contains the start of every row and the end of the last row plus one.

    - nnz_total_dev_host_ptr – [out] total number of nonzero elements in device or host memory.

    - info – [in] prune information structure

    - temp_buffer – [out] buffer allocated by the user whose size is determined by calling rocsparse_xprune_dense2csr_buffer_size().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m` or `n` or `lda` or `percentage` is invalid.

    - rocsparse_status_invalid_pointer – `A` or `descr` or `info` or `csr_row_ptr` or `nnz_total_dev_host_ptr` or `temp_buffer` pointer is invalid.

### rocsparse_prune_dense2csr_by_percentage()

rocsparse_status rocsparse_sprune_dense2csr_by_percentage(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const float *A, rocsparse_int lda, float percentage, const rocsparse_mat_descr descr, float *csr_val, const rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind, rocsparse_mat_info info, void *temp_buffer)

rocsparse_status rocsparse_dprune_dense2csr_by_percentage(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const double *A, rocsparse_int lda, double percentage, const rocsparse_mat_descr descr, double *csr_val, const rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind, rocsparse_mat_info info, void *temp_buffer)

  This function converts the matrix A in dense format into a sparse matrix in CSR format while pruning values based on percentage.

  When converting and pruning a dense matrix A to a CSR matrix by percentage the following steps are performed. First the user calls `rocsparse_prune_dense2csr_by_percentage_buffer_size` which determines the size of the temporary storage buffer. Once determined, this buffer must be allocated by the user. Next the user allocates the csr_row_ptr array to have `m+1` elements and calls `rocsparse_prune_dense2csr_nnz_by_percentage`. Finally the user finishes the conversion by allocating the csr_col_ind and csr_val arrays (whos size is determined by the value at nnz_total_dev_host_ptr) and calling `rocsparse_prune_dense2csr_by_percentage`.

  The pruning by percentage works by first sorting the absolute values of the dense matrix `A`. We then determine a position in this sorted array by

  \[ pos = ceil(m*n*(percentage/100)) - 1 pos = min(pos, m*n-1) pos = max(pos, 0) threshold = sorted_A[pos] \]
  Once we have this threshold we prune values in the dense matrix `A` as in `rocsparse_prune_dense2csr`.

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows of the dense matrix `A`.

    - n – [in] number of columns of the dense matrix `A`.

    - A – [in] array of dimensions (`lda`, `n`)

    - lda – [in] leading dimension of dense array `A`.

    - percentage – [in] percentage >= 0 and percentage <= 100.

    - descr – [in] the descriptor of the dense matrix `A`, the supported matrix type is rocsparse_matrix_type_general and also any valid value of the rocsparse_index_base.

    - csr_val – [out] array of nnz ( = `csr_row_ptr`[m] - `csr_row_ptr`[0] ) nonzero elements of matrix `A`.

    - csr_row_ptr – [in] integer array of `m+1` elements that contains the start of every row and the end of the last row plus one.

    - csr_col_ind – [out] integer array of nnz ( = `csr_row_ptr`[m] - csr_row_ptr[0] ) column indices of the non-zero elements of matrix `A`.

    - info – [in] prune information structure

    - temp_buffer – [in] temporary storage buffer allocated by the user, size is returned by rocsparse_xprune_dense2csr_buffer_size().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m` or `n` or `lda` or `percentage` is invalid.

    - rocsparse_status_invalid_pointer – `A` or `descr` or `info` or `csr_val` or `csr_row_ptr` or `csr_col_ind` or `temp_buffer` pointer is invalid.

### rocsparse_prune_csr2csr_by_percentage_buffer_size()

rocsparse_status rocsparse_sprune_csr2csr_by_percentage_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz_A, const rocsparse_mat_descr csr_descr_A, const float *csr_val_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, float percentage, const rocsparse_mat_descr csr_descr_C, const float *csr_val_C, const rocsparse_int *csr_row_ptr_C, const rocsparse_int *csr_col_ind_C, rocsparse_mat_info info, size_t *buffer_size)

rocsparse_status rocsparse_dprune_csr2csr_by_percentage_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz_A, const rocsparse_mat_descr csr_descr_A, const double *csr_val_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, double percentage, const rocsparse_mat_descr csr_descr_C, const double *csr_val_C, const rocsparse_int *csr_row_ptr_C, const rocsparse_int *csr_col_ind_C, rocsparse_mat_info info, size_t *buffer_size)

  Convert and prune by percentage a sparse CSR matrix into a sparse CSR matrix.

  `rocsparse_prune_csr2csr__by_percentage_buffer_size` returns the size of the temporary buffer that is required by `rocsparse_sprune_csr2csr_nnz_by_percentage`, `rocsparse_dprune_csr2csr_nnz_by_percentage`, `rocsparse_sprune_csr2csr_by_percentage`, and `rocsparse_dprune_csr2csr_by_percentage`. The temporary storage buffer must be allocated by the user.

  Note

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

  Note

  This routine supports execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows in the sparse CSR matrix.

    - n – [in] number of columns in the sparse CSR matrix.

    - nnz_A – [in] number of non-zeros in the sparse CSR matrix A.

    - csr_descr_A – [in] descriptor of the sparse CSR matrix A. Currently, only rocsparse_matrix_type_general is supported.

    - csr_val_A – [in] array of `nnz_A` elements containing the values of the sparse CSR matrix A.

    - csr_row_ptr_A – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix A.

    - csr_col_ind_A – [in] array of `nnz_A` elements containing the column indices of the sparse CSR matrix A.

    - percentage – [in] percentage >= 0 and percentage <= 100.

    - csr_descr_C – [in] descriptor of the sparse CSR matrix C. Currently, only rocsparse_matrix_type_general is supported.

    - csr_val_C – [in] array of `nnz_C` elements containing the values of the sparse CSR matrix C.

    - csr_row_ptr_C – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix C.

    - csr_col_ind_C – [in] array of `nnz_C` elements containing the column indices of the sparse CSR matrix C.

    - info – [in] prune info structure.

    - buffer_size – [out] number of bytes of the temporary storage buffer required by `rocsparse_sprune_csr2csr_nnz_by_percentage`, `rocsparse_dprune_csr2csr_nnz_by_percentage`, `rocsparse_sprune_csr2csr_by_percentage`, and `rocsparse_dprune_csr2csr_by_percentage`.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_pointer – `buffer_size` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

### rocsparse_prune_csr2csr_nnz_by_percentage()

rocsparse_status rocsparse_sprune_csr2csr_nnz_by_percentage(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz_A, const rocsparse_mat_descr csr_descr_A, const float *csr_val_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, float percentage, const rocsparse_mat_descr csr_descr_C, rocsparse_int *csr_row_ptr_C, rocsparse_int *nnz_total_dev_host_ptr, rocsparse_mat_info info, void *temp_buffer)

rocsparse_status rocsparse_dprune_csr2csr_nnz_by_percentage(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz_A, const rocsparse_mat_descr csr_descr_A, const double *csr_val_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, double percentage, const rocsparse_mat_descr csr_descr_C, rocsparse_int *csr_row_ptr_C, rocsparse_int *nnz_total_dev_host_ptr, rocsparse_mat_info info, void *temp_buffer)

  Convert and prune by percentage a sparse CSR matrix into a sparse CSR matrix.

  `rocsparse_prune_csr2csr_nnz_by_percentage` computes the number of nonzero elements per row and the total number of nonzero elements in a sparse CSR matrix once elements less than the threshold are pruned from the matrix.

  Note

  The routine does support asynchronous execution if the pointer mode is set to device.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows in the sparse CSR matrix.

    - n – [in] number of columns in the sparse CSR matrix.

    - nnz_A – [in] number of non-zeros in the sparse CSR matrix A.

    - csr_descr_A – [in] descriptor of the sparse CSR matrix A. Currently, only rocsparse_matrix_type_general is supported.

    - csr_val_A – [in] array of `nnz_A` elements containing the values of the sparse CSR matrix A.

    - csr_row_ptr_A – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix A.

    - csr_col_ind_A – [in] array of `nnz_A` elements containing the column indices of the sparse CSR matrix A.

    - percentage – [in] percentage >= 0 and percentage <= 100.

    - csr_descr_C – [in] descriptor of the sparse CSR matrix C. Currently, only rocsparse_matrix_type_general is supported.

    - csr_row_ptr_C – [out] array of `m+1` elements that point to the start of every row of the sparse CSR matrix C.

    - nnz_total_dev_host_ptr – [out] total number of nonzero elements in device or host memory.

    - info – [in] prune info structure.

    - temp_buffer – [out] buffer allocated by the user whose size is determined by calling `rocsparse_xprune_csr2csr_by_percentage_buffer_size()`.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m` or `n` or `nnz_A` or `percentage` is invalid.

    - rocsparse_status_invalid_pointer – `csr_descr_A` or `csr_descr_C` or `info` or `csr_val_A` or `csr_row_ptr_A` or `csr_col_ind_A` or `csr_row_ptr_C` or `nnz_total_dev_host_ptr` or `temp_buffer` pointer is invalid.

### rocsparse_prune_csr2csr_by_percentage()

rocsparse_status rocsparse_sprune_csr2csr_by_percentage(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz_A, const rocsparse_mat_descr csr_descr_A, const float *csr_val_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, float percentage, const rocsparse_mat_descr csr_descr_C, float *csr_val_C, const rocsparse_int *csr_row_ptr_C, rocsparse_int *csr_col_ind_C, rocsparse_mat_info info, void *temp_buffer)

rocsparse_status rocsparse_dprune_csr2csr_by_percentage(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz_A, const rocsparse_mat_descr csr_descr_A, const double *csr_val_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, double percentage, const rocsparse_mat_descr csr_descr_C, double *csr_val_C, const rocsparse_int *csr_row_ptr_C, rocsparse_int *csr_col_ind_C, rocsparse_mat_info info, void *temp_buffer)

  Convert and prune by percentage a sparse CSR matrix into a sparse CSR matrix.

  This function converts the sparse CSR matrix A into a sparse CSR matrix C by pruning values in A that are less than the threshold. All the parameters are assumed to have been pre-allocated by the user. The user first calls rocsparse_xprune_csr2csr_buffer_size() to determine the size of the buffer used by rocsparse_xprune_csr2csr_nnz() and rocsparse_xprune_csr2csr() which the user then allocates. The user then allocates `csr_row_ptr_C` to have `m+1` elements and then calls rocsparse_xprune_csr2csr_nnz() which fills in the `csr_row_ptr_C` array stores then number of elements that are larger than the pruning threshold in `nnz_total_dev_host_ptr`. The user then calls rocsparse_xprune_csr2csr() to complete the conversion.

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows in the sparse CSR matrix.

    - n – [in] number of columns in the sparse CSR matrix.

    - nnz_A – [in] number of non-zeros in the sparse CSR matrix A.

    - csr_descr_A – [in] descriptor of the sparse CSR matrix A. Currently, only rocsparse_matrix_type_general is supported.

    - csr_val_A – [in] array of `nnz_A` elements containing the values of the sparse CSR matrix A.

    - csr_row_ptr_A – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix A.

    - csr_col_ind_A – [in] array of `nnz_A` elements containing the column indices of the sparse CSR matrix A.

    - percentage – [in] percentage >= 0 and percentage <= 100.

    - csr_descr_C – [in] descriptor of the sparse CSR matrix C. Currently, only rocsparse_matrix_type_general is supported.

    - csr_val_C – [out] array of `nnz_C` elements containing the values of the sparse CSR matrix C.

    - csr_row_ptr_C – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix C.

    - csr_col_ind_C – [out] array of `nnz_C` elements containing the column indices of the sparse CSR matrix C.

    - info – [in] prune info structure.

    - temp_buffer – [in] buffer allocated by the user whose size is determined by calling `rocsparse_xprune_csr2csr_buffer_size()`.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m` or `n` or `nnz_A` or `percentage` is invalid.

    - rocsparse_status_invalid_pointer – `csr_descr_A` or `csr_descr_C` or `info` or `csr_val_A` or `csr_row_ptr_A` or `csr_col_ind_A` or `csr_val_C` or `csr_row_ptr_C` or `csr_col_ind_C` or `temp_buffer` pointer is invalid.

### rocsparse_rocsparse_bsrpad_value()

rocsparse_status rocsparse_sbsrpad_value(rocsparse_handle handle, rocsparse_int m, rocsparse_int mb, rocsparse_int nnzb, rocsparse_int block_dim, float value, const rocsparse_mat_descr bsr_descr, float *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind)

rocsparse_status rocsparse_dbsrpad_value(rocsparse_handle handle, rocsparse_int m, rocsparse_int mb, rocsparse_int nnzb, rocsparse_int block_dim, double value, const rocsparse_mat_descr bsr_descr, double *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind)

rocsparse_status rocsparse_cbsrpad_value(rocsparse_handle handle, rocsparse_int m, rocsparse_int mb, rocsparse_int nnzb, rocsparse_int block_dim, rocsparse_float_complex value, const rocsparse_mat_descr bsr_descr, rocsparse_float_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind)

rocsparse_status rocsparse_zbsrpad_value(rocsparse_handle handle, rocsparse_int m, rocsparse_int mb, rocsparse_int nnzb, rocsparse_int block_dim, rocsparse_double_complex value, const rocsparse_mat_descr bsr_descr, rocsparse_double_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind)

  Pads a value to the diagonal of the last block (if the last block is a diagonal block) in the sparse BSR matrix when the matrix expands outside m x m.

  When converting from a CSR matrix to a BSR matrix the resulting BSR matrix will be larger when m < mb * block_dim. In these situations, the CSR to BSR conversion will expand the BSR matrix to have zeros when outside m x m. This routine converts the resulting BSR matrix to one that has a value on the last diagonal blocks diagonal if this last block is a diagonal block in the BSR matrix.

  Note

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

  Note

  This routine supports execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows of the sparse BSR matrix.

    - mb – [in] number of block rows of the sparse BSR matrix.

    - nnzb – [in] number of non-zero blocks of the sparse BSR matrix.

    - block_dim – [in] block dimension of the sparse BSR matrix.

    - value – [in] scalar value that is set on the diagonal of the last block when the matrix expands outside of `m` x `m`

    - bsr_descr – [in] descriptor of the sparse BSR matrix. Currently, only rocsparse_matrix_type_general is supported.

    - bsr_val – [inout] array of `nnzb` blocks of the sparse BSR matrix.

    - bsr_row_ptr – [in] array of `mb+1` elements that point to the start of every block row of the sparse BSR matrix.

    - bsr_col_ind – [in] array of `nnzb` elements containing the block column indices of the sparse BSR matrix.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m`, `mb`, `nnzb` or `block_dim` is invalid.

    - rocsparse_status_invalid_pointer – `bsr_descr`, `bsr_val`, `bsr_row_ind`, `bsr_col_ind`, pointer is invalid.

## Reordering Functions

This module holds all sparse reordering routines.

The sparse reordering routines describe algorithm for reordering sparse matrices.

The routines in this module do not support execution in a hipGraph context.

### rocsparse_csrcolor()

rocsparse_status rocsparse_scsrcolor(rocsparse_handle handle, rocsparse_int m, rocsparse_int nnz, const rocsparse_mat_descr descr, const float *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, const float *fraction_to_color, rocsparse_int *ncolors, rocsparse_int *coloring, rocsparse_int *reordering, rocsparse_mat_info info)

rocsparse_status rocsparse_dcsrcolor(rocsparse_handle handle, rocsparse_int m, rocsparse_int nnz, const rocsparse_mat_descr descr, const double *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, const double *fraction_to_color, rocsparse_int *ncolors, rocsparse_int *coloring, rocsparse_int *reordering, rocsparse_mat_info info)

rocsparse_status rocsparse_ccsrcolor(rocsparse_handle handle, rocsparse_int m, rocsparse_int nnz, const rocsparse_mat_descr descr, const rocsparse_float_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, const float *fraction_to_color, rocsparse_int *ncolors, rocsparse_int *coloring, rocsparse_int *reordering, rocsparse_mat_info info)

rocsparse_status rocsparse_zcsrcolor(rocsparse_handle handle, rocsparse_int m, rocsparse_int nnz, const rocsparse_mat_descr descr, const rocsparse_double_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, const double *fraction_to_color, rocsparse_int *ncolors, rocsparse_int *coloring, rocsparse_int *reordering, rocsparse_mat_info info)

  Coloring of the adjacency graph of the matrix \(A\) stored in the CSR format.

  `rocsparse_csrcolor` performs the coloring of the undirected graph represented by the (symmetric) sparsity pattern of the matrix \(A\) stored in CSR format. Graph coloring is a way of coloring the nodes of a graph such that no two adjacent nodes are of the same color. The `fraction_to_color` is a parameter to only color a given percentage of the graph nodes, the remaining uncolored nodes receive distinct new colors. The optional `reordering` array is a permutation array such that unknowns of the same color are grouped. The matrix \(A\) must be stored as a general matrix with a symmetric sparsity pattern, and if the matrix \(A\) is non-symmetric then the user is responsible to provide the symmetric part \(\frac{A+A^T}{2}\).

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows of sparse matrix \(A\).

    - nnz – [in] number of non-zero entries of sparse matrix \(A\).

    - descr – [in] sparse matrix descriptor.

    - csr_val – [in] array of `nnz` elements of the sparse CSR matrix.

    - csr_row_ptr – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix.

    - csr_col_ind – [in] array of `nnz` elements containing the column indices of the sparse CSR matrix.

    - fraction_to_color – [in] fraction of nodes to be colored, which should be in the interval [0.0,1.0], for example 0.8 implies that 80 percent of nodes will be colored.

    - ncolors – [out] resulting number of distinct colors.

    - coloring – [out] resulting mapping of colors.

    - reordering – [out] optional resulting reordering permutation if `reordering` is a non-null pointer.

    - info – [inout] structure that holds the information collected during the coloring algorithm.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_size – `m` or `nnz` is invalid.

    - rocsparse_status_invalid_pointer – `descr`, `csr_val`, `csr_row_ptr`, `csr_col_ind`, `fraction_to_color`, `ncolors`, `coloring` or `info` pointer is invalid.

## Utility Functions

This module holds all sparse utility routines.

The sparse utility routines allow for testing whether matrix data is valid for different matrix formats

The routines in this module do not support execution in a hipGraph context.

### rocsparse_check_matrix_csr_buffer_size()

rocsparse_status rocsparse_scheck_matrix_csr_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const float *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, size_t *buffer_size)

rocsparse_status rocsparse_dcheck_matrix_csr_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const double *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, size_t *buffer_size)

rocsparse_status rocsparse_ccheck_matrix_csr_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const rocsparse_float_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, size_t *buffer_size)

rocsparse_status rocsparse_zcheck_matrix_csr_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const rocsparse_double_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, size_t *buffer_size)

  Check matrix to see if it is valid.

  `rocsparse_check_matrix_csr_buffer_size` computes the required buffer size needed when calling `rocsparse_check_matrix_csr`

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows of the sparse CSR matrix.

    - n – [in] number of columns of the sparse CSR matrix.

    - nnz – [in] number of non-zero entries of the sparse CSR matrix.

    - csr_val – [in] array of `nnz` elements of the sparse CSR matrix.

    - csr_row_ptr – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix.

    - csr_col_ind – [in] array of `nnz` elements containing the column indices of the sparse CSR matrix.

    - idx_base – [in] rocsparse_index_base_zero or rocsparse_index_base_one.

    - matrix_type – [in] rocsparse_matrix_type_general, rocsparse_matrix_type_symmetric, rocsparse_matrix_type_hermitian or rocsparse_matrix_type_triangular.

    - uplo – [in] rocsparse_fill_mode_lower or rocsparse_fill_mode_upper.

    - storage – [in] rocsparse_storage_mode_sorted or rocsparse_storage_mode_sorted.

    - buffer_size – [out] number of bytes of the temporary storage buffer required by rocsparse_scheck_matrix_csr(), rocsparse_dcheck_matrix_csr(), rocsparse_ccheck_matrix_csr() and rocsparse_zcheck_matrix_csr().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_value – `idx_base` or `matrix_type` or `uplo` or `storage` is invalid.

    - rocsparse_status_invalid_size – `m` `n` or `nnz` is invalid.

    - rocsparse_status_invalid_pointer – `csr_val`, `csr_row_ptr`, `csr_col_ind` or `buffer_size` pointer is invalid.

### rocsparse_check_matrix_csr()

rocsparse_status rocsparse_scheck_matrix_csr(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const float *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, rocsparse_data_status *data_status, void *temp_buffer)

rocsparse_status rocsparse_dcheck_matrix_csr(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const double *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, rocsparse_data_status *data_status, void *temp_buffer)

rocsparse_status rocsparse_ccheck_matrix_csr(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const rocsparse_float_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, rocsparse_data_status *data_status, void *temp_buffer)

rocsparse_status rocsparse_zcheck_matrix_csr(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const rocsparse_double_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, rocsparse_data_status *data_status, void *temp_buffer)

  Check matrix to see if it is valid.

  `rocsparse_check_matrix_csr` checks if the input CSR matrix is valid.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows of the sparse CSR matrix.

    - n – [in] number of columns of the sparse CSR matrix.

    - nnz – [in] number of non-zero entries of the sparse CSR matrix.

    - csr_val – [in] array of `nnz` elements of the sparse CSR matrix.

    - csr_row_ptr – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix.

    - csr_col_ind – [in] array of `nnz` elements containing the column indices of the sparse CSR matrix.

    - idx_base – [in] rocsparse_index_base_zero or rocsparse_index_base_one.

    - matrix_type – [in] rocsparse_matrix_type_general, rocsparse_matrix_type_symmetric, rocsparse_matrix_type_hermitian or rocsparse_matrix_type_triangular.

    - uplo – [in] rocsparse_fill_mode_lower or rocsparse_fill_mode_upper.

    - storage – [in] rocsparse_storage_mode_sorted or rocsparse_storage_mode_sorted.

    - data_status – [out] modified to indicate the status of the data

    - temp_buffer – [in] temporary storage buffer allocated by the user.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_value – `idx_base` or `matrix_type` or `uplo` or `storage` is invalid.

    - rocsparse_status_invalid_size – `m` `n` or `nnz` is invalid.

    - rocsparse_status_invalid_pointer – `csr_val`, `csr_row_ptr`, `csr_col_ind`, `temp_buffer` or `data_status` pointer is invalid.

### rocsparse_check_matrix_csc_buffer_size()

rocsparse_status rocsparse_scheck_matrix_csc_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const float *csc_val, const rocsparse_int *csc_col_ptr, const rocsparse_int *csc_row_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, size_t *buffer_size)

rocsparse_status rocsparse_dcheck_matrix_csc_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const double *csc_val, const rocsparse_int *csc_col_ptr, const rocsparse_int *csc_row_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, size_t *buffer_size)

rocsparse_status rocsparse_ccheck_matrix_csc_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const rocsparse_float_complex *csc_val, const rocsparse_int *csc_col_ptr, const rocsparse_int *csc_row_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, size_t *buffer_size)

rocsparse_status rocsparse_zcheck_matrix_csc_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const rocsparse_double_complex *csc_val, const rocsparse_int *csc_col_ptr, const rocsparse_int *csc_row_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, size_t *buffer_size)

  Check matrix to see if it is valid.

  `rocsparse_check_matrix_csc_buffer_size` computes the required buffer size needed when calling `rocsparse_check_matrix_csc`

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows of the sparse CSC matrix.

    - n – [in] number of columns of the sparse CSC matrix.

    - nnz – [in] number of non-zero entries of the sparse CSC matrix.

    - csc_val – [in] array of `nnz` elements of the sparse CSC matrix.

    - csc_col_ptr – [in] array of `m+1` elements that point to the start of every column of the sparse CSC matrix.

    - csc_row_ind – [in] array of `nnz` elements containing the row indices of the sparse CSC matrix.

    - idx_base – [in] rocsparse_index_base_zero or rocsparse_index_base_one.

    - matrix_type – [in] rocsparse_matrix_type_general, rocsparse_matrix_type_symmetric, rocsparse_matrix_type_hermitian or rocsparse_matrix_type_triangular.

    - uplo – [in] rocsparse_fill_mode_lower or rocsparse_fill_mode_upper.

    - storage – [in] rocsparse_storage_mode_sorted or rocsparse_storage_mode_sorted.

    - buffer_size – [out] number of bytes of the temporary storage buffer required by rocsparse_scheck_matrix_csc(), rocsparse_dcheck_matrix_csc(), rocsparse_ccheck_matrix_csc() and rocsparse_zcheck_matrix_csc().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_value – `idx_base` or `matrix_type` or `uplo` or `storage` is invalid.

    - rocsparse_status_invalid_size – `m` `n` or `nnz` is invalid.

    - rocsparse_status_invalid_pointer – `csc_val`, `csc_col_ptr`, `csc_row_ind` or `buffer_size` pointer is invalid.

### rocsparse_check_matrix_csc()

rocsparse_status rocsparse_scheck_matrix_csc(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const float *csc_val, const rocsparse_int *csc_col_ptr, const rocsparse_int *csc_row_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, rocsparse_data_status *data_status, void *temp_buffer)

rocsparse_status rocsparse_dcheck_matrix_csc(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const double *csc_val, const rocsparse_int *csc_col_ptr, const rocsparse_int *csc_row_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, rocsparse_data_status *data_status, void *temp_buffer)

rocsparse_status rocsparse_ccheck_matrix_csc(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const rocsparse_float_complex *csc_val, const rocsparse_int *csc_col_ptr, const rocsparse_int *csc_row_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, rocsparse_data_status *data_status, void *temp_buffer)

rocsparse_status rocsparse_zcheck_matrix_csc(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const rocsparse_double_complex *csc_val, const rocsparse_int *csc_col_ptr, const rocsparse_int *csc_row_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, rocsparse_data_status *data_status, void *temp_buffer)

  Check matrix to see if it is valid.

  `rocsparse_check_matrix_csc` checks if the input CSC matrix is valid.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows of the sparse CSC matrix.

    - n – [in] number of columns of the sparse CSC matrix.

    - nnz – [in] number of non-zero entries of the sparse CSC matrix.

    - csc_val – [in] array of `nnz` elements of the sparse CSC matrix.

    - csc_col_ptr – [in] array of `m+1` elements that point to the start of every column of the sparse CSC matrix.

    - csc_row_ind – [in] array of `nnz` elements containing the row indices of the sparse CSC matrix.

    - idx_base – [in] rocsparse_index_base_zero or rocsparse_index_base_one.

    - matrix_type – [in] rocsparse_matrix_type_general, rocsparse_matrix_type_symmetric, rocsparse_matrix_type_hermitian or rocsparse_matrix_type_triangular.

    - uplo – [in] rocsparse_fill_mode_lower or rocsparse_fill_mode_upper.

    - storage – [in] rocsparse_storage_mode_sorted or rocsparse_storage_mode_sorted.

    - data_status – [out] modified to indicate the status of the data

    - temp_buffer – [in] temporary storage buffer allocated by the user.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_value – `idx_base` or `matrix_type` or `uplo` or `storage` is invalid.

    - rocsparse_status_invalid_size – `m` `n` or `nnz` is invalid.

    - rocsparse_status_invalid_pointer – `csc_val`, `csc_col_ptr`, `csc_row_ind`, `temp_buffer` or `data_status` pointer is invalid.

### rocsparse_check_matrix_coo_buffer_size()

rocsparse_status rocsparse_scheck_matrix_coo_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const float *coo_val, const rocsparse_int *coo_row_ind, const rocsparse_int *coo_col_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, size_t *buffer_size)

rocsparse_status rocsparse_dcheck_matrix_coo_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const double *coo_val, const rocsparse_int *coo_row_ind, const rocsparse_int *coo_col_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, size_t *buffer_size)

rocsparse_status rocsparse_ccheck_matrix_coo_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const rocsparse_float_complex *coo_val, const rocsparse_int *coo_row_ind, const rocsparse_int *coo_col_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, size_t *buffer_size)

rocsparse_status rocsparse_zcheck_matrix_coo_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const rocsparse_double_complex *coo_val, const rocsparse_int *coo_row_ind, const rocsparse_int *coo_col_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, size_t *buffer_size)

  Check matrix to see if it is valid.

  `rocsparse_check_matrix_coo_buffer_size` computes the required buffer size needed when calling `rocsparse_check_matrix_coo`

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows of the sparse CSR matrix.

    - n – [in] number of columns of the sparse CSR matrix.

    - nnz – [in] number of non-zero entries of the sparse CSR matrix.

    - coo_val – [in] array of `nnz` elements of the sparse COO matrix.

    - coo_row_ind – [in] array of `nnz` elements containing the row indices of the sparse COO matrix.

    - coo_col_ind – [in] array of `nnz` elements containing the column indices of the sparse COO matrix.

    - idx_base – [in] rocsparse_index_base_zero or rocsparse_index_base_one.

    - matrix_type – [in] rocsparse_matrix_type_general, rocsparse_matrix_type_symmetric, rocsparse_matrix_type_hermitian or rocsparse_matrix_type_triangular.

    - uplo – [in] rocsparse_fill_mode_lower or rocsparse_fill_mode_upper.

    - storage – [in] rocsparse_storage_mode_sorted or rocsparse_storage_mode_sorted.

    - buffer_size – [out] number of bytes of the temporary storage buffer required by rocsparse_scheck_matrix_coo(), rocsparse_dcheck_matrix_coo(), rocsparse_ccheck_matrix_coo() and rocsparse_zcheck_matrix_coo().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_value – `idx_base` or `matrix_type` or `uplo` or `storage` is invalid.

    - rocsparse_status_invalid_size – `m` `n` or `nnz` is invalid.

    - rocsparse_status_invalid_pointer – `coo_val`, `coo_row_ind`, `coo_col_ind` or `buffer_size` pointer is invalid.

### rocsparse_check_matrix_coo()

rocsparse_status rocsparse_scheck_matrix_coo(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const float *coo_val, const rocsparse_int *coo_row_ind, const rocsparse_int *coo_col_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, rocsparse_data_status *data_status, void *temp_buffer)

rocsparse_status rocsparse_dcheck_matrix_coo(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const double *coo_val, const rocsparse_int *coo_row_ind, const rocsparse_int *coo_col_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, rocsparse_data_status *data_status, void *temp_buffer)

rocsparse_status rocsparse_ccheck_matrix_coo(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const rocsparse_float_complex *coo_val, const rocsparse_int *coo_row_ind, const rocsparse_int *coo_col_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, rocsparse_data_status *data_status, void *temp_buffer)

rocsparse_status rocsparse_zcheck_matrix_coo(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const rocsparse_double_complex *coo_val, const rocsparse_int *coo_row_ind, const rocsparse_int *coo_col_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, rocsparse_data_status *data_status, void *temp_buffer)

  Check matrix to see if it is valid.

  `rocsparse_check_matrix_coo` checks if the input COO matrix is valid.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows of the sparse COO matrix.

    - n – [in] number of columns of the sparse COO matrix.

    - nnz – [in] number of non-zero entries of the sparse COO matrix.

    - coo_val – [in] array of `nnz` elements of the sparse COO matrix.

    - coo_row_ind – [in] array of `nnz` elements containing the row indices of the sparse COO matrix.

    - coo_col_ind – [in] array of `nnz` elements containing the column indices of the sparse COO matrix.

    - idx_base – [in] rocsparse_index_base_zero or rocsparse_index_base_one.

    - matrix_type – [in] rocsparse_matrix_type_general, rocsparse_matrix_type_symmetric, rocsparse_matrix_type_hermitian or rocsparse_matrix_type_triangular.

    - uplo – [in] rocsparse_fill_mode_lower or rocsparse_fill_mode_upper.

    - storage – [in] rocsparse_storage_mode_sorted or rocsparse_storage_mode_sorted.

    - data_status – [out] modified to indicate the status of the data

    - temp_buffer – [in] temporary storage buffer allocated by the user.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_value – `idx_base` or `matrix_type` or `uplo` or `storage` is invalid.

    - rocsparse_status_invalid_size – `m` `n` or `nnz` is invalid.

    - rocsparse_status_invalid_pointer – `coo_val`, `coo_row_ind`, `coo_col_ind`, `temp_buffer` or `data_status` pointer is invalid.

### rocsparse_check_matrix_gebsr_buffer_size()

rocsparse_status rocsparse_scheck_matrix_gebsr_buffer_size(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, rocsparse_int row_block_dim, rocsparse_int col_block_dim, const float *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, size_t *buffer_size)

rocsparse_status rocsparse_dcheck_matrix_gebsr_buffer_size(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, rocsparse_int row_block_dim, rocsparse_int col_block_dim, const double *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, size_t *buffer_size)

rocsparse_status rocsparse_ccheck_matrix_gebsr_buffer_size(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, rocsparse_int row_block_dim, rocsparse_int col_block_dim, const rocsparse_float_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, size_t *buffer_size)

rocsparse_status rocsparse_zcheck_matrix_gebsr_buffer_size(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, rocsparse_int row_block_dim, rocsparse_int col_block_dim, const rocsparse_double_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, size_t *buffer_size)

  Check matrix to see if it is valid.

  `rocsparse_check_matrix_gebsr_buffer_size` computes the required buffer size needed when calling `rocsparse_check_matrix_gebsr`

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - dir – [in] matrix storage of GEBSR blocks.

    - mb – [in] number of block rows of the sparse GEBSR matrix.

    - nb – [in] number of block columns of the sparse GEBSR matrix.

    - nnzb – [in] number of non-zero blocks of the sparse GEBSR matrix.

    - row_block_dim – [in] row block dimension of the sparse GEBSR matrix.

    - col_block_dim – [in] column block dimension of the sparse GEBSR matrix.

    - bsr_val – [in] array of `nnzb` elements of the sparse GEBSR matrix.

    - bsr_row_ptr – [in] array of `mb+1` elements that point to the start of every row of the sparse GEBSR matrix.

    - bsr_col_ind – [in] array of `nnzb` elements containing the column indices of the sparse GEBSR matrix.

    - idx_base – [in] rocsparse_index_base_zero or rocsparse_index_base_one.

    - matrix_type – [in] rocsparse_matrix_type_general, rocsparse_matrix_type_symmetric, rocsparse_matrix_type_hermitian or rocsparse_matrix_type_triangular.

    - uplo – [in] rocsparse_fill_mode_lower or rocsparse_fill_mode_upper.

    - storage – [in] rocsparse_storage_mode_sorted or rocsparse_storage_mode_sorted.

    - buffer_size – [out] number of bytes of the temporary storage buffer required by rocsparse_scheck_matrix_gebsr(), rocsparse_dcheck_matrix_gebsr(), rocsparse_ccheck_matrix_gebsr() and rocsparse_zcheck_matrix_gebsr().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_value – `dir` or `idx_base` or `matrix_type` or `uplo` or `storage` is invalid.

    - rocsparse_status_invalid_size – `mb` `nb` `nnzb` `row_block_dim` or `col_block_dim` is invalid.

    - rocsparse_status_invalid_pointer – `bsr_val`, `bsr_row_ptr`, `bsr_col_ind` or `buffer_size` pointer is invalid.

### rocsparse_check_matrix_gebsr()

rocsparse_status rocsparse_scheck_matrix_gebsr(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, rocsparse_int row_block_dim, rocsparse_int col_block_dim, const float *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, rocsparse_data_status *data_status, void *temp_buffer)

rocsparse_status rocsparse_dcheck_matrix_gebsr(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, rocsparse_int row_block_dim, rocsparse_int col_block_dim, const double *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, rocsparse_data_status *data_status, void *temp_buffer)

rocsparse_status rocsparse_ccheck_matrix_gebsr(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, rocsparse_int row_block_dim, rocsparse_int col_block_dim, const rocsparse_float_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, rocsparse_data_status *data_status, void *temp_buffer)

rocsparse_status rocsparse_zcheck_matrix_gebsr(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, rocsparse_int row_block_dim, rocsparse_int col_block_dim, const rocsparse_double_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, rocsparse_data_status *data_status, void *temp_buffer)

  Check matrix to see if it is valid.

  `rocsparse_check_matrix_gebsr` checks if the input GEBSR matrix is valid.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - dir – [in] matrix storage of GEBSR blocks.

    - mb – [in] number of block rows of the sparse GEBSR matrix.

    - nb – [in] number of block columns of the sparse GEBSR matrix.

    - nnzb – [in] number of non-zero blocks of the sparse GEBSR matrix.

    - row_block_dim – [in] row block dimension of the sparse GEBSR matrix.

    - col_block_dim – [in] column block dimension of the sparse GEBSR matrix.

    - bsr_val – [in] array of `nnzb` elements of the sparse GEBSR matrix.

    - bsr_row_ptr – [in] array of `mb+1` elements that point to the start of every row of the sparse GEBSR matrix.

    - bsr_col_ind – [in] array of `nnzb` elements containing the column indices of the sparse GEBSR matrix.

    - idx_base – [in] rocsparse_index_base_zero or rocsparse_index_base_one.

    - matrix_type – [in] rocsparse_matrix_type_general, rocsparse_matrix_type_symmetric, rocsparse_matrix_type_hermitian or rocsparse_matrix_type_triangular.

    - uplo – [in] rocsparse_fill_mode_lower or rocsparse_fill_mode_upper.

    - storage – [in] rocsparse_storage_mode_sorted or rocsparse_storage_mode_sorted.

    - data_status – [out] modified to indicate the status of the data

    - temp_buffer – [in] temporary storage buffer allocated by the user.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_value – `dir` or `idx_base` or `matrix_type` or `uplo` or `storage` is invalid.

    - rocsparse_status_invalid_size – `mb` `nb` `nnzb` `row_block_dim` or `col_block_dim` is invalid.

    - rocsparse_status_invalid_pointer – `bsr_val`, `bsr_row_ptr`, `bsr_col_ind`, `temp_buffer` or `data_status` pointer is invalid.

### rocsparse_check_matrix_gebsc_buffer_size()

rocsparse_status rocsparse_scheck_matrix_gebsc_buffer_size(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, rocsparse_int row_block_dim, rocsparse_int col_block_dim, const float *bsc_val, const rocsparse_int *bsc_col_ptr, const rocsparse_int *bsc_row_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, size_t *buffer_size)

rocsparse_status rocsparse_dcheck_matrix_gebsc_buffer_size(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, rocsparse_int row_block_dim, rocsparse_int col_block_dim, const double *bsc_val, const rocsparse_int *bsc_col_ptr, const rocsparse_int *bsc_row_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, size_t *buffer_size)

rocsparse_status rocsparse_ccheck_matrix_gebsc_buffer_size(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, rocsparse_int row_block_dim, rocsparse_int col_block_dim, const rocsparse_float_complex *bsc_val, const rocsparse_int *bsc_col_ptr, const rocsparse_int *bsc_row_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, size_t *buffer_size)

rocsparse_status rocsparse_zcheck_matrix_gebsc_buffer_size(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, rocsparse_int row_block_dim, rocsparse_int col_block_dim, const rocsparse_double_complex *bsc_val, const rocsparse_int *bsc_col_ptr, const rocsparse_int *bsc_row_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, size_t *buffer_size)

  Check matrix to see if it is valid.

  `rocsparse_check_matrix_gebsc_buffer_size` computes the required buffer size needed when calling `rocsparse_check_matrix_gebsc`

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - dir – [in] matrix storage of GEBSC blocks.

    - mb – [in] number of block rows of the sparse GEBSC matrix.

    - nb – [in] number of block columns of the sparse GEBSC matrix.

    - nnzb – [in] number of non-zero blocks of the sparse GEBSC matrix.

    - row_block_dim – [in] row block dimension of the sparse GEBSC matrix.

    - col_block_dim – [in] column block dimension of the sparse GEBSC matrix.

    - bsc_val – [in] array of `nnzb` elements of the sparse GEBSC matrix.

    - bsc_col_ptr – [in] array of `nb+1` elements that point to the start of every column of the sparse GEBSC matrix.

    - bsc_row_ind – [in] array of `nnzb` elements containing the row indices of the sparse GEBSC matrix.

    - idx_base – [in] rocsparse_index_base_zero or rocsparse_index_base_one.

    - matrix_type – [in] rocsparse_matrix_type_general, rocsparse_matrix_type_symmetric, rocsparse_matrix_type_hermitian or rocsparse_matrix_type_triangular.

    - uplo – [in] rocsparse_fill_mode_lower or rocsparse_fill_mode_upper.

    - storage – [in] rocsparse_storage_mode_sorted or rocsparse_storage_mode_sorted.

    - buffer_size – [out] number of bytes of the temporary storage buffer required by rocsparse_scheck_matrix_gebsc(), rocsparse_dcheck_matrix_gebsc(), rocsparse_ccheck_matrix_gebsc() and rocsparse_zcheck_matrix_gebsc().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_value – `dir` or `idx_base` or `matrix_type` or `uplo` or `storage` is invalid.

    - rocsparse_status_invalid_size – `mb` `nb` `nnzb` `row_block_dim` or `col_block_dim` is invalid.

    - rocsparse_status_invalid_pointer – `bsc_val`, `bsc_col_ptr`, `bsc_row_ind` or `buffer_size` pointer is invalid.

### rocsparse_check_matrix_gebsc()

rocsparse_status rocsparse_scheck_matrix_gebsc(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, rocsparse_int row_block_dim, rocsparse_int col_block_dim, const float *bsc_val, const rocsparse_int *bsc_col_ptr, const rocsparse_int *bsc_row_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, rocsparse_data_status *data_status, void *temp_buffer)

rocsparse_status rocsparse_dcheck_matrix_gebsc(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, rocsparse_int row_block_dim, rocsparse_int col_block_dim, const double *bsc_val, const rocsparse_int *bsc_col_ptr, const rocsparse_int *bsc_row_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, rocsparse_data_status *data_status, void *temp_buffer)

rocsparse_status rocsparse_ccheck_matrix_gebsc(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, rocsparse_int row_block_dim, rocsparse_int col_block_dim, const rocsparse_float_complex *bsc_val, const rocsparse_int *bsc_col_ptr, const rocsparse_int *bsc_row_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, rocsparse_data_status *data_status, void *temp_buffer)

rocsparse_status rocsparse_zcheck_matrix_gebsc(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, rocsparse_int row_block_dim, rocsparse_int col_block_dim, const rocsparse_double_complex *bsc_val, const rocsparse_int *bsc_col_ptr, const rocsparse_int *bsc_row_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, rocsparse_data_status *data_status, void *temp_buffer)

  Check matrix to see if it is valid.

  `rocsparse_check_matrix_gebsc` checks if the input GEBSC matrix is valid.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - dir – [in] matrix storage of GEBSC blocks.

    - mb – [in] number of block rows of the sparse GEBSC matrix.

    - nb – [in] number of block columns of the sparse GEBSC matrix.

    - nnzb – [in] number of non-zero blocks of the sparse GEBSC matrix.

    - row_block_dim – [in] row block dimension of the sparse GEBSC matrix.

    - col_block_dim – [in] column block dimension of the sparse GEBSC matrix.

    - bsc_val – [in] array of `nnzb` elements of the sparse GEBSC matrix.

    - bsc_col_ptr – [in] array of `nb+1` elements that point to the start of every column of the sparse GEBSC matrix.

    - bsc_row_ind – [in] array of `nnzb` elements containing the row indices of the sparse GEBSC matrix.

    - idx_base – [in] rocsparse_index_base_zero or rocsparse_index_base_one.

    - matrix_type – [in] rocsparse_matrix_type_general, rocsparse_matrix_type_symmetric, rocsparse_matrix_type_hermitian or rocsparse_matrix_type_triangular.

    - uplo – [in] rocsparse_fill_mode_lower or rocsparse_fill_mode_upper.

    - storage – [in] rocsparse_storage_mode_sorted or rocsparse_storage_mode_sorted.

    - data_status – [out] modified to indicate the status of the data

    - temp_buffer – [in] temporary storage buffer allocated by the user.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_value – `dir` or `idx_base` or `matrix_type` or `uplo` or `storage` is invalid.

    - rocsparse_status_invalid_size – `mb` `nb` `nnzb` `row_block_dim` or `col_block_dim` is invalid.

    - rocsparse_status_invalid_pointer – `bsc_val`, `bsc_col_ptr`, `bsc_row_ind`, `temp_buffer` or `data_status` pointer is invalid.

### rocsparse_check_matrix_ell_buffer_size()

rocsparse_status rocsparse_scheck_matrix_ell_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int ell_width, const float *ell_val, const rocsparse_int *ell_col_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, size_t *buffer_size)

rocsparse_status rocsparse_dcheck_matrix_ell_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int ell_width, const double *ell_val, const rocsparse_int *ell_col_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, size_t *buffer_size)

rocsparse_status rocsparse_ccheck_matrix_ell_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int ell_width, const rocsparse_float_complex *ell_val, const rocsparse_int *ell_col_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, size_t *buffer_size)

rocsparse_status rocsparse_zcheck_matrix_ell_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int ell_width, const rocsparse_double_complex *ell_val, const rocsparse_int *ell_col_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, size_t *buffer_size)

  Check matrix to see if it is valid.

  `rocsparse_check_matrix_ell_buffer_size` computes the required buffer size needed when calling `rocsparse_check_matrix_ell`

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows of the sparse ELL matrix.

    - n – [in] number of columns of the sparse ELL matrix.

    - ell_width – [in] number of non-zero elements per row of the sparse ELL matrix.

    - ell_val – [in] array that contains the elements of the sparse ELL matrix. Padded elements should be zero.

    - ell_col_ind – [in] array that contains the column indices of the sparse ELL matrix. Padded column indices should be -1.

    - idx_base – [in] rocsparse_index_base_zero or rocsparse_index_base_one.

    - matrix_type – [in] rocsparse_matrix_type_general, rocsparse_matrix_type_symmetric, rocsparse_matrix_type_hermitian or rocsparse_matrix_type_triangular.

    - uplo – [in] rocsparse_fill_mode_lower or rocsparse_fill_mode_upper.

    - storage – [in] rocsparse_storage_mode_sorted or rocsparse_storage_mode_sorted.

    - buffer_size – [out] number of bytes of the temporary storage buffer required by rocsparse_scheck_matrix_ell(), rocsparse_dcheck_matrix_ell(), rocsparse_ccheck_matrix_ell() and rocsparse_zcheck_matrix_ell().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_value – `idx_base` or `matrix_type` or `uplo` or `storage` is invalid.

    - rocsparse_status_invalid_size – `m` `n` or `ell_width` is invalid.

    - rocsparse_status_invalid_pointer – `ell_val`, `ell_col_ind` or `buffer_size` pointer is invalid.

### rocsparse_check_matrix_ell()

rocsparse_status rocsparse_scheck_matrix_ell(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int ell_width, const float *ell_val, const rocsparse_int *ell_col_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, rocsparse_data_status *data_status, void *temp_buffer)

rocsparse_status rocsparse_dcheck_matrix_ell(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int ell_width, const double *ell_val, const rocsparse_int *ell_col_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, rocsparse_data_status *data_status, void *temp_buffer)

rocsparse_status rocsparse_ccheck_matrix_ell(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int ell_width, const rocsparse_float_complex *ell_val, const rocsparse_int *ell_col_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, rocsparse_data_status *data_status, void *temp_buffer)

rocsparse_status rocsparse_zcheck_matrix_ell(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int ell_width, const rocsparse_double_complex *ell_val, const rocsparse_int *ell_col_ind, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, rocsparse_data_status *data_status, void *temp_buffer)

  Check matrix to see if it is valid.

  `rocsparse_check_matrix_ell` checks if the input ELL matrix is valid.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - m – [in] number of rows of the sparse ELL matrix.

    - n – [in] number of columns of the sparse ELL matrix.

    - ell_width – [in] number of non-zero elements per row of the sparse ELL matrix.

    - ell_val – [in] array that contains the elements of the sparse ELL matrix. Padded elements should be zero.

    - ell_col_ind – [in] array that contains the column indices of the sparse ELL matrix. Padded column indices should be -1.

    - idx_base – [in] rocsparse_index_base_zero or rocsparse_index_base_one.

    - matrix_type – [in] rocsparse_matrix_type_general, rocsparse_matrix_type_symmetric, rocsparse_matrix_type_hermitian or rocsparse_matrix_type_triangular.

    - uplo – [in] rocsparse_fill_mode_lower or rocsparse_fill_mode_upper.

    - storage – [in] rocsparse_storage_mode_sorted or rocsparse_storage_mode_sorted.

    - data_status – [out] modified to indicate the status of the data

    - temp_buffer – [in] temporary storage buffer allocated by the user.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_value – `idx_base` or `matrix_type` or `uplo` or `storage` is invalid.

    - rocsparse_status_invalid_size – `m` `n` or `ell_width` is invalid.

    - rocsparse_status_invalid_pointer – `ell_val`, `ell_col_ind`, `temp_buffer` or `data_status` pointer is invalid.

### rocsparse_check_matrix_hyb_buffer_size()

rocsparse_status rocsparse_check_matrix_hyb_buffer_size(rocsparse_handle handle, const rocsparse_hyb_mat hyb, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, size_t *buffer_size)

  Check matrix to see if it is valid.

  `rocsparse_check_matrix_hyb_buffer_size` computes the required buffer size needed when calling `rocsparse_check_matrix_hyb`

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - hyb – [in] matrix in HYB storage format.

    - idx_base – [in] rocsparse_index_base_zero or rocsparse_index_base_one.

    - matrix_type – [in] rocsparse_matrix_type_general, rocsparse_matrix_type_symmetric, rocsparse_matrix_type_hermitian or rocsparse_matrix_type_triangular.

    - uplo – [in] rocsparse_fill_mode_lower or rocsparse_fill_mode_upper.

    - storage – [in] rocsparse_storage_mode_sorted or rocsparse_storage_mode_sorted.

    - buffer_size – [out] number of bytes of the temporary storage buffer required by rocsparse_check_matrix_hyb().

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_value – `idx_base` or `matrix_type` or `uplo` or `storage` is invalid.

    - rocsparse_status_invalid_pointer – `hyb` or `buffer_size` pointer is invalid.

### rocsparse_check_matrix_hyb()

rocsparse_status rocsparse_check_matrix_hyb(rocsparse_handle handle, const rocsparse_hyb_mat hyb, rocsparse_index_base idx_base, rocsparse_matrix_type matrix_type, rocsparse_fill_mode uplo, rocsparse_storage_mode storage, rocsparse_data_status *data_status, void *temp_buffer)

  Check matrix to see if it is valid.

  `rocsparse_check_matrix_hyb` checks if the input HYB matrix is valid.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - hyb – [in] matrix in HYB storage format.

    - idx_base – [in] rocsparse_index_base_zero or rocsparse_index_base_one.

    - matrix_type – [in] rocsparse_matrix_type_general, rocsparse_matrix_type_symmetric, rocsparse_matrix_type_hermitian or rocsparse_matrix_type_triangular.

    - uplo – [in] rocsparse_fill_mode_lower or rocsparse_fill_mode_upper.

    - storage – [in] rocsparse_storage_mode_sorted or rocsparse_storage_mode_sorted.

    - data_status – [out] modified to indicate the status of the data

    - temp_buffer – [in] temporary storage buffer allocated by the user.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_value – `idx_base` or `matrix_type` or `uplo` or `storage` is invalid.

    - rocsparse_status_invalid_pointer – `hyb` or `data_status` pointer is invalid.

## Sparse Generic Functions

This module holds all sparse generic routines.

The sparse generic routines describe operations that manipulate sparse matrices.

### rocsparse_axpby()

rocsparse_status rocsparse_axpby(rocsparse_handle handle, const void *alpha, const rocsparse_spvec_descr x, const void *beta, rocsparse_dnvec_descr y)

  Scale a sparse vector and add it to a scaled dense vector.

  rocsparse_axpby multiplies the sparse vector \(x\) with scalar \(\alpha\) and adds the result to the dense vector \(y\) that is multiplied with scalar \(\beta\), such that

  \[ y := \alpha \cdot x + \beta \cdot y \]

      for(i = 0; i < nnz; ++i)
      {
          y[x_ind[i]] = alpha * x_val[i] + beta * y[x_ind[i]]
      }

  Note

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

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - alpha – [in] scalar \(\alpha\).

    - x – [in] sparse matrix descriptor.

    - beta – [in] scalar \(\beta\).

    - y – [inout] dense matrix descriptor.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_pointer – `alpha`, `x`, `beta` or `y` pointer is invalid.

### rocsparse_gather()

rocsparse_status rocsparse_gather(rocsparse_handle handle, const rocsparse_dnvec_descr y, rocsparse_spvec_descr x)

  Gather elements from a dense vector and store them into a sparse vector.

  rocsparse_gather gathers the elements from the dense vector \(y\) and stores them in the sparse vector \(x\).

      for(i = 0; i < nnz; ++i)
      {
          x_val[i] = y[x_ind[i]];
      }

  Note

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

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - y – [in] dense vector \(y\).

    - x – [out] sparse vector \(x\).

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_pointer – `x` or `y` pointer is invalid.

### rocsparse_scatter()

rocsparse_status rocsparse_scatter(rocsparse_handle handle, const rocsparse_spvec_descr x, rocsparse_dnvec_descr y)

  Scatter elements from a sparse vector into a dense vector.

  rocsparse_scatter scatters the elements from the sparse vector \(x\) in the dense vector \(y\).

      for(i = 0; i < nnz; ++i)
      {
          y[x_ind[i]] = x_val[i];
      }

  Note

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

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - x – [in] sparse vector \(x\).

    - y – [out] dense vector \(y\).

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_pointer – `x` or `y` pointer is invalid.

### rocsparse_rot()

rocsparse_status rocsparse_rot(rocsparse_handle handle, const void *c, const void *s, rocsparse_spvec_descr x, rocsparse_dnvec_descr y)

  Apply Givens rotation to a dense and a sparse vector.

  rocsparse_rot applies the Givens rotation matrix \(G\) to the sparse vector \(x\) and the dense vector \(y\), where

  \[\begin{split} G = \begin{pmatrix} c & s \\ -s & c \end{pmatrix} \end{split}\]

      for(i = 0; i < nnz; ++i)
      {
          x_tmp = x_val[i];
          y_tmp = y[x_ind[i]];

          x_val[i]    = c * x_tmp + s * y_tmp;
          y[x_ind[i]] = c * y_tmp - s * x_tmp;
      }

  Note

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

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - c – [in] pointer to the cosine element of \(G\), can be on host or device.

    - s – [in] pointer to the sine element of \(G\), can be on host or device.

    - x – [inout] sparse vector \(x\).

    - y – [inout] dense vector \(y\).

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_pointer – `c`, `s`, `x` or `y` pointer is invalid.

### rocsparse_spvv()

rocsparse_status rocsparse_spvv(rocsparse_handle handle, rocsparse_operation trans, const rocsparse_spvec_descr x, const rocsparse_dnvec_descr y, void *result, rocsparse_datatype compute_type, size_t *buffer_size, void *temp_buffer)

  Sparse vector inner dot product.

  rocsparse_spvv computes the inner dot product of the sparse vecotr \(x\) with the dense vector \(y\), such that

  \[ \text{result} := x^{'} \cdot y, \]
  with
  \[\begin{split} op(x) = \left\{ \begin{array}{ll} x, & \text{if trans == rocsparse_operation_none} \\ \bar{x}, & \text{if trans == rocsparse_operation_conjugate_transpose} \\ \end{array} \right. \end{split}\]

      result = 0;
      for(i = 0; i < nnz; ++i)
      {
          result += x_val[i] * y[x_ind[i]];
      }

  Example

        // Number of non-zeros of the sparse vector
        int nnz = 3;

        // Size of sparse and dense vector
        int size = 9;

        // Sparse index vector
        std::vector<int> hx_ind = {0, 3, 5};

        // Sparse value vector
        std::vector<float> hx_val = {1.0f, 2.0f, 3.0f};

        // Dense vector
        std::vector<float> hy = {1.0f, 2.0f, 3.0f, 4.0f, 5.0f, 6.0f, 7.0f, 8.0f, 9.0f};

        // Offload data to device
        int* dx_ind;
        float* dx_val;
        float* dy;
        hipMalloc((void**)&dx_ind, sizeof(int) * nnz);
        hipMalloc((void**)&dx_val, sizeof(float) * nnz);
        hipMalloc((void**)&dy, sizeof(float) * size);

        hipMemcpy(dx_ind, hx_ind.data(), sizeof(int) * nnz, hipMemcpyHostToDevice);
        hipMemcpy(dx_val, hx_val.data(), sizeof(float) * nnz, hipMemcpyHostToDevice);
        hipMemcpy(dy, hy.data(), sizeof(float) * size, hipMemcpyHostToDevice);

        rocsparse_handle     handle;
        rocsparse_spvec_descr vecX;
        rocsparse_dnvec_descr vecY;

        rocsparse_indextype idx_type = rocsparse_indextype_i32;
        rocsparse_datatype  data_type = rocsparse_datatype_f32_r;
        rocsparse_datatype  compute_type = rocsparse_datatype_f32_r;
        rocsparse_operation trans = rocsparse_operation_none;
        rocsparse_index_base idx_base = rocsparse_index_base_zero;

        rocsparse_create_handle(&handle);

        // Create sparse vector X
        rocsparse_create_spvec_descr(&vecX,
                                     size,
                                     nnz,
                                     dx_ind,
                                     dx_val,
                                     idx_type,
                                     idx_base,
                                     data_type);

        // Create dense vector Y
        rocsparse_create_dnvec_descr(&vecY,
                                     size,
                                     dy,
                                     data_type);

        // Obtain buffer size
        float hresult = 0.0f;
        size_t buffer_size;
        rocsparse_spvv(handle,
                       trans,
                       vecX,
                       vecY,
                       &hresult,
                       compute_type,
                       &buffer_size,
                       nullptr);

        void* temp_buffer;
        hipMalloc(&temp_buffer, buffer_size);

        // SpVV
        rocsparse_spvv(handle,
                       trans,
                       vecX,
                       vecY,
                       &hresult,
                       compute_type,
                       &buffer_size,
                       temp_buffer);

        hipDeviceSynchronize();

        std::cout << "hresult: " << hresult << std::endl;

        // Clear rocSPARSE
        rocsparse_destroy_spvec_descr(vecX);
        rocsparse_destroy_dnvec_descr(vecY);
        rocsparse_destroy_handle(handle);

        // Clear device memory
        hipFree(dx_ind);
        hipFree(dx_val);
        hipFree(dy);
        hipFree(temp_buffer);

  Note

  This function writes the required allocation size (in bytes) to `buffer_size` and returns without performing the SpVV operation, when a nullptr is passed for `temp_buffer`.

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - trans – [in] sparse vector operation type.

    - x – [in] sparse vector descriptor.

    - y – [in] dense vector descriptor.

    - result – [out] pointer to the result, can be host or device memory

    - compute_type – [in] floating point precision for the SpVV computation.

    - buffer_size – [out] number of bytes of the temporary storage buffer. buffer_size is set when `temp_buffer` is nullptr.

    - temp_buffer – [in] temporary storage buffer allocated by the user. When a nullptr is passed, the required allocation size (in bytes) is written to `buffer_size` and function returns without performing the SpVV operation.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_pointer – `x`, `y`, `result` or `buffer_size` pointer is invalid.

    - rocsparse_status_not_implemented – `compute_type` is currently not supported.

### rocsparse_spmv()

rocsparse_status rocsparse_spmv(rocsparse_handle handle, rocsparse_operation trans, const void *alpha, const rocsparse_spmat_descr mat, const rocsparse_dnvec_descr x, const void *beta, const rocsparse_dnvec_descr y, rocsparse_datatype compute_type, rocsparse_spmv_alg alg, size_t *buffer_size, void *temp_buffer)

  Sparse matrix vector multiplication.

  rocsparse_spmv multiplies the scalar \(\alpha\) with a sparse \(m \times n\) matrix and the dense vector \(x\) and adds the result to the dense vector \(y\) that is multiplied by the scalar \(\beta\), such that

  \[ y := \alpha \cdot op(A) \cdot x + \beta \cdot y, \]
  with
  \[\begin{split} op(A) = \left\{ \begin{array}{ll} A, & \text{if trans == rocsparse_operation_none} \\ A^T, & \text{if trans == rocsparse_operation_transpose} \\ A^H, & \text{if trans == rocsparse_operation_conjugate_transpose} \end{array} \right. \end{split}\]

  rocsparse_spmv supports multiple combinations of data types and compute types. The tables below indicate the currently supported different data types that can be used for for the sparse matrix A and the dense vectors X and Y and the compute type for \(\alpha\) and \(\beta\). The advantage of using different data types is to save on memory bandwidth and storage when a user application allows while performing the actual computation in a higher precision.

  Uniform Precisions:

      *  |----------------------------------------------------|
      *  |             A / X / Y / compute_type               |
      *  |----------------------------------------------------|
      *  |             rocsparse_datatype_f32_r               |
      *  |----------------------------------------------------|
      *  |             rocsparse_datatype_f64_r               |
      *  |----------------------------------------------------|
      *  |             rocsparse_datatype_f32_c               |
      *  |----------------------------------------------------|
      *  |             rocsparse_datatype_f64_c               |
      *  |----------------------------------------------------|
      *

  Mixed precisions:

      *  |-------------------------|--------------------------|--------------------------|
      *  |         A / X           |             Y            |       compute_type       |
      *  |-------------------------|--------------------------|--------------------------|
      *  | rocsparse_datatype_i8_r | rocsparse_datatype_i32_r | rocsparse_datatype_i32_r |
      *  |-------------------------|--------------------------|--------------------------|
      *  | rocsparse_datatype_i8_r | rocsparse_datatype_f32_r | rocsparse_datatype_f32_r |
      *  |-------------------------|--------------------------|--------------------------|
      *  | rocsparse_datatype_i8_r | rocsparse_datatype_i32_r | rocsparse_datatype_i32_r |
      *  |-------------------------|--------------------------|--------------------------|
      *

  Mixed-regular real precisions

      *  |----------------------------|----------------------------|
      *  |              A             |    X / Y / compute_type    |
      *  |----------------------------|----------------------------|
      *  |  rocsparse_datatype_f32_r  |  rocsparse_datatype_f64_r  |
      *  |----------------------------|----------------------------|
      *  |  rocsparse_datatype_f32_c  |  rocsparse_datatype_f64_c  |
      *  |----------------------------|----------------------------|
      *

  Mixed-regular Complex precisions

      *  |----------------------------|----------------------------|
      *  |              A             |    X / Y / compute_type    |
      *  |----------------------------|----------------------------|
      *  |  rocsparse_datatype_f32_r  |  rocsparse_datatype_f32_c  |
      *  |----------------------------|----------------------------|
      *  |  rocsparse_datatype_f64_r  |  rocsparse_datatype_f64_c  |
      *  |----------------------------|----------------------------|
      *

  Note

  This function writes the required allocation size (in bytes) to `buffer_size` and returns without performing the SpMV operation, when a nullptr is passed for `temp_buffer`.

  Note

  Only the rocsparse_spmv_stage_buffer_size stage and the rocsparse_spmv_stage_compute stage are non blocking and executed asynchronously with respect to the host. They may return before the actual computation has finished. The rocsparse_spmv_stage_preprocess stage is blocking with respect to the host.

  Note

  Only the rocsparse_spmv_stage_buffer_size stage and the rocsparse_spmv_stage_compute stage support execution in a hipGraph context. The rocsparse_spmv_stage_preprocess stage does not support hipGraph.

  Note

  The sparse matrix formats currently supported are: rocsparse_format_bsr, rocsparse_format_coo, rocsparse_format_coo_aos, rocsparse_format_csr, rocsparse_format_csc and rocsparse_format_ell.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - trans – [in] matrix operation type.

    - alpha – [in] scalar \(\alpha\).

    - mat – [in] matrix descriptor.

    - x – [in] vector descriptor.

    - beta – [in] scalar \(\beta\).

    - y – [inout] vector descriptor.

    - compute_type – [in] floating point precision for the SpMV computation.

    - alg – [in] SpMV algorithm for the SpMV computation.

    - buffer_size – [out] number of bytes of the temporary storage buffer. buffer_size is set when `temp_buffer` is nullptr.

    - temp_buffer – [in] temporary storage buffer allocated by the user. When a nullptr is passed, the required allocation size (in bytes) is written to `buffer_size` and function returns without performing the SpMV operation.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_pointer – `alpha`, `mat`, `x`, `beta`, `y` or `buffer_size` pointer is invalid.

    - rocsparse_status_invalid_value – the value of `trans`, `trans_B`, `compute_type`, `alg` is incorrect.

    - rocsparse_status_not_implemented – `compute_type` or `alg` is currently not supported.

### rocsparse_spmv_ex()

rocsparse_status rocsparse_spmv_ex(rocsparse_handle handle, rocsparse_operation trans, const void *alpha, const rocsparse_spmat_descr mat, const rocsparse_dnvec_descr x, const void *beta, const rocsparse_dnvec_descr y, rocsparse_datatype compute_type, rocsparse_spmv_alg alg, rocsparse_spmv_stage stage, size_t *buffer_size, void *temp_buffer)

  Sparse matrix vector multiplication.

  rocsparse_spmv_ex multiplies the scalar \(\alpha\) with a sparse \(m \times n\) matrix and the dense vector \(x\) and adds the result to the dense vector \(y\) that is multiplied by the scalar \(\beta\), such that

  \[ y := \alpha \cdot op(A) \cdot x + \beta \cdot y, \]
  with
  \[\begin{split} op(A) = \left\{ \begin{array}{ll} A, & \text{if trans == rocsparse_operation_none} \\ A^T, & \text{if trans == rocsparse_operation_transpose} \\ A^H, & \text{if trans == rocsparse_operation_conjugate_transpose} \end{array} \right. \end{split}\]

  rocsparse_spmv supports multiple combinations of data types and compute types. The tables below indicate the currently supported different data types that can be used for for the sparse matrix A and the dense vectors X and Y and the compute type for \(\alpha\) and \(\beta\). The advantage of using different data types is to save on memory bandwidth and storage when a user application allows while performing the actual computation in a higher precision.

  Uniform Precisions:

      *  |----------------------------------------------------|
      *  |             A / X / Y / compute_type               |
      *  |----------------------------------------------------|
      *  |             rocsparse_datatype_f32_r               |
      *  |----------------------------------------------------|
      *  |             rocsparse_datatype_f64_r               |
      *  |----------------------------------------------------|
      *  |             rocsparse_datatype_f32_c               |
      *  |----------------------------------------------------|
      *  |             rocsparse_datatype_f64_c               |
      *  |----------------------------------------------------|
      *

  Mixed-regular real precisions

      *  |----------------------------|----------------------------|
      *  |              A             |    X / Y / compute_type    |
      *  |----------------------------|----------------------------|
      *  |  rocsparse_datatype_f32_r  |  rocsparse_datatype_f64_r  |
      *  |----------------------------|----------------------------|
      *  |  rocsparse_datatype_f32_c  |  rocsparse_datatype_f64_c  |
      *  |----------------------------|----------------------------|
      *

  Mixed precisions:

      *  |-------------------------|--------------------------|--------------------------|
      *  |         A / X           |             Y            |       compute_type       |
      *  |-------------------------|--------------------------|--------------------------|
      *  | rocsparse_datatype_i8_r | rocsparse_datatype_i32_r | rocsparse_datatype_i32_r |
      *  |-------------------------|--------------------------|--------------------------|
      *  | rocsparse_datatype_i8_r | rocsparse_datatype_f32_r | rocsparse_datatype_f32_r |
      *  |-------------------------|--------------------------|--------------------------|
      *  | rocsparse_datatype_i8_r | rocsparse_datatype_i32_r | rocsparse_datatype_i32_r |
      *  |-------------------------|--------------------------|--------------------------|
      *

  Mixed-regular Complex precisions

      *  |----------------------------|----------------------------|
      *  |              A             |    X / Y / compute_type    |
      *  |----------------------------|----------------------------|
      *  |  rocsparse_datatype_f32_r  |  rocsparse_datatype_f32_c  |
      *  |----------------------------|----------------------------|
      *  |  rocsparse_datatype_f64_r  |  rocsparse_datatype_f64_c  |
      *  |----------------------------|----------------------------|
      *

  Note

  This function writes the required allocation size (in bytes) to `buffer_size` and returns without performing the SpMV operation, when a nullptr is passed for `temp_buffer`.

  Note

  The sparse matrix formats currently supported are: rocsparse_format_bsr, rocsparse_format_coo, rocsparse_format_coo_aos, rocsparse_format_csr, rocsparse_format_csc and rocsparse_format_ell.

  Note

  SpMV_ex requires three stages to complete. The first stage rocsparse_spmv_stage_buffer_size will return the size of the temporary storage buffer that is required for subsequent calls to rocsparse_spmv_ex. The second stage rocsparse_spmv_stage_preprocess will preprocess data that would be saved in the temporary storage buffer. In the final stage rocsparse_spmv_stage_compute, the actual computation is performed.

  Note

  If rocsparse_spmv_stage_auto is selected, rocSPARSE will automatically detect which stage is required based on the following indicators: If `temp_buffer` is equal to `nullptr`, the required buffer size will be returned. Else, the SpMV_ex preprocess and the SpMV algorithm will be executed.

  Note

  Only the rocsparse_spmv_stage_buffer_size stage and the rocsparse_spmv_stage_compute stage are non blocking and executed asynchronously with respect to the host. They may return before the actual computation has finished. The rocsparse_spmv_stage_preprocess stage is blocking with respect to the host.

  Note

  Only the rocsparse_spmv_stage_buffer_size stage and the rocsparse_spmv_stage_compute stage support execution in a hipGraph context. The rocsparse_spmv_stage_preprocess stage does not support hipGraph.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - trans – [in] matrix operation type.

    - alpha – [in] scalar \(\alpha\).

    - mat – [in] matrix descriptor.

    - x – [in] vector descriptor.

    - beta – [in] scalar \(\beta\).

    - y – [inout] vector descriptor.

    - compute_type – [in] floating point precision for the SpMV computation.

    - alg – [in] SpMV algorithm for the SpMV computation.

    - stage – [in] SpMV stage for the SpMV computation.

    - buffer_size – [out] number of bytes of the temporary storage buffer. buffer_size is set when `temp_buffer` is nullptr.

    - temp_buffer – [in] temporary storage buffer allocated by the user. When a nullptr is passed, the required allocation size (in bytes) is written to `buffer_size` and function returns without performing the SpMV operation.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_pointer – `alpha`, `mat`, `x`, `beta`, `y` or `buffer_size` pointer is invalid.

    - rocsparse_status_invalid_value – the value of `trans`, `trans_B`, `compute_type`, `alg` or `stage` is incorrect.

    - rocsparse_status_not_implemented – `compute_type` or `alg` is currently not supported.

### rocsparse_spsv()

rocsparse_status rocsparse_spsv(rocsparse_handle handle, rocsparse_operation trans, const void *alpha, const rocsparse_spmat_descr mat, const rocsparse_dnvec_descr x, const rocsparse_dnvec_descr y, rocsparse_datatype compute_type, rocsparse_spsv_alg alg, rocsparse_spsv_stage stage, size_t *buffer_size, void *temp_buffer)

  Sparse triangular solve.

  `rocsparse_spsv_solve` solves a sparse triangular linear system of a sparse \(m \times m\) matrix, defined in CSR or COO storage format, a dense solution vector \(y\) and the right-hand side \(x\) that is multiplied by \(\alpha\), such that

  \[ op(A) \cdot y = \alpha \cdot x, \]
  with
  \[\begin{split} op(A) = \left\{ \begin{array}{ll} A, & \text{if trans == rocsparse_operation_none} \\ A^T, & \text{if trans == rocsparse_operation_transpose} \\ A^H, & \text{if trans == rocsparse_operation_conjugate_transpose} \end{array} \right. \end{split}\]

  Note

  SpSV requires three stages to complete. The first stage rocsparse_spsv_stage_buffer_size will return the size of the temporary storage buffer that is required for subsequent calls. The second stage rocsparse_spsv_stage_preprocess will preprocess data that would be saved in the temporary storage buffer. In the final stage rocsparse_spsv_stage_compute, the actual computation is performed.

  Note

  If rocsparse_spsv_stage_auto is selected, rocSPARSE will automatically detect which stage is required based on the following indicators: If `temp_buffer` is equal to `nullptr`, the required buffer size will be returned. If `buffer_size` is equal to `nullptr`, analysis will be performed. Otherwise, the SpSV preprocess and the SpSV algorithm will be executed.

  Note

  Only the rocsparse_spsv_stage_buffer_size stage and the rocsparse_spsv_stage_compute stage are non blocking and executed asynchronously with respect to the host. They may return before the actual computation has finished. The rocsparse_spsv_stage_preprocess stage is blocking with respect to the host.

  Note

  Currently, only `trans` == rocsparse_operation_none and `trans` == rocsparse_operation_transpose is supported.

  Note

  Only the rocsparse_spsv_stage_buffer_size stage and the rocsparse_spsv_stage_compute stage support execution in a hipGraph context. The rocsparse_spsv_stage_preprocess stage does not support hipGraph.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - trans – [in] matrix operation type.

    - alpha – [in] scalar \(\alpha\).

    - mat – [in] matrix descriptor.

    - x – [in] vector descriptor.

    - y – [inout] vector descriptor.

    - compute_type – [in] floating point precision for the SpSV computation.

    - alg – [in] SpSV algorithm for the SpSV computation.

    - stage – [in] SpSV stage for the SpSV computation.

    - buffer_size – [out] number of bytes of the temporary storage buffer.

    - temp_buffer – [in] temporary storage buffer allocated by the user. When a nullptr is passed, the required allocation size (in bytes) is written to `buffer_size` and function returns without performing the SpSV operation.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_pointer – `alpha`, `mat`, `x`, `y`, `descr` or `buffer_size` pointer is invalid.

    - rocsparse_status_not_implemented – `trans`, `compute_type`, `stage` or `alg` is currently not supported.

### rocsparse_spsm()

rocsparse_status rocsparse_spsm(rocsparse_handle handle, rocsparse_operation trans_A, rocsparse_operation trans_B, const void *alpha, const rocsparse_spmat_descr matA, const rocsparse_dnmat_descr matB, const rocsparse_dnmat_descr matC, rocsparse_datatype compute_type, rocsparse_spsm_alg alg, rocsparse_spsm_stage stage, size_t *buffer_size, void *temp_buffer)

  Sparse triangular system solve.

  `rocsparse_spsm_solve` solves a sparse triangular linear system of a sparse \(m \times m\) matrix, defined in CSR or COO storage format, a dense solution matrix \(C\) and the right-hand side \(B\) that is multiplied by \(\alpha\), such that

  \[ op(A) \cdot C = \alpha \cdot op(B), \]
  with
  \[\begin{split} op(A) = \left\{ \begin{array}{ll} A, & \text{if trans == rocsparse_operation_none} \\ A^T, & \text{if trans == rocsparse_operation_transpose} \\ A^H, & \text{if trans == rocsparse_operation_conjugate_transpose} \end{array} \right. \end{split}\]
  and
  \[\begin{split} op(B) = \left\{ \begin{array}{ll} B, & \text{if trans_B == rocsparse_operation_none} \\ B^T, & \text{if trans_B == rocsparse_operation_transpose} \\ B^H, & \text{if trans_B == rocsparse_operation_conjugate_transpose} \end{array} \right. \end{split}\]

  Note

  SpSM requires three stages to complete. The first stage rocsparse_spsm_stage_buffer_size will return the size of the temporary storage buffer that is required for subsequent calls. The second stage rocsparse_spsm_stage_preprocess will preprocess data that would be saved in the temporary storage buffer. In the final stage rocsparse_spsm_stage_compute, the actual computation is performed.

  Note

  If rocsparse_spsm_stage_auto is selected, rocSPARSE will automatically detect which stage is required based on the following indicators: If `temp_buffer` is equal to `nullptr`, the required buffer size will be returned. If `buffer_size` is equal to `nullptr`, analysis will be performed. Otherwise, the SpSM preprocess and the SpSM algorithm will be executed.

  Note

  Only the rocsparse_spsm_stage_buffer_size stage and the rocsparse_spsm_stage_compute stage are non blocking and executed asynchronously with respect to the host. They may return before the actual computation has finished. The rocsparse_spsm_stage_preprocess stage is blocking with respect to the host.

  Note

  Currently, only `trans_A` == rocsparse_operation_none and `trans_A` == rocsparse_operation_transpose is supported. Currently, only `trans_B` == rocsparse_operation_none and `trans_B` == rocsparse_operation_transpose is supported.

  Note

  Only the rocsparse_spsm_stage_buffer_size stage and the rocsparse_spsm_stage_compute stage support execution in a hipGraph context. The rocsparse_spsm_stage_preprocess stage does not support hipGraph.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - trans_A – [in] matrix operation type for the sparse matrix A.

    - trans_B – [in] matrix operation type for the dense matrix B.

    - alpha – [in] scalar \(\alpha\).

    - matA – [in] sparse matrix descriptor.

    - matB – [in] dense matrix descriptor.

    - matC – [inout] dense matrix descriptor.

    - compute_type – [in] floating point precision for the SpSM computation.

    - alg – [in] SpSM algorithm for the SpSM computation.

    - stage – [in] SpSM stage for the SpSM computation.

    - buffer_size – [out] number of bytes of the temporary storage buffer.

    - temp_buffer – [in] temporary storage buffer allocated by the user. When a nullptr is passed, the required allocation size (in bytes) is written to `buffer_size` and function returns without performing the SpSM operation.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_pointer – `alpha`, `matA`, `matB`, `matC`, `descr` or `buffer_size` pointer is invalid.

    - rocsparse_status_not_implemented – `trans_A`, `trans_B`, `compute_type`, `stage` or `alg` is currently not supported.

### rocsparse_spmm()

rocsparse_status rocsparse_spmm(rocsparse_handle handle, rocsparse_operation trans_A, rocsparse_operation trans_B, const void *alpha, const rocsparse_spmat_descr mat_A, const rocsparse_dnmat_descr mat_B, const void *beta, const rocsparse_dnmat_descr mat_C, rocsparse_datatype compute_type, rocsparse_spmm_alg alg, rocsparse_spmm_stage stage, size_t *buffer_size, void *temp_buffer)

  Sparse matrix dense matrix multiplication, extension routine.

  `rocsparse_spmm` (or `rocsparse_spmm_ex` ) multiplies the scalar \(\alpha\) with a sparse \(m \times k\) matrix \(A\), defined in CSR or COO or Blocked ELL storage format, and the dense \(k \times n\) matrix \(B\) and adds the result to the dense \(m \times n\) matrix \(C\) that is multiplied by the scalar \(\beta\), such that

  \[ C := \alpha \cdot op(A) \cdot op(B) + \beta \cdot C, \]
  with
  \[\begin{split} op(A) = \left\{ \begin{array}{ll} A, & \text{if trans_A == rocsparse_operation_none} \\ A^T, & \text{if trans_A == rocsparse_operation_transpose} \\ A^H, & \text{if trans_A == rocsparse_operation_conjugate_transpose} \end{array} \right. \end{split}\]
  and
  \[\begin{split} op(B) = \left\{ \begin{array}{ll} B, & \text{if trans_B == rocsparse_operation_none} \\ B^T, & \text{if trans_B == rocsparse_operation_transpose} \\ B^H, & \text{if trans_B == rocsparse_operation_conjugate_transpose} \end{array} \right. \end{split}\]

  Example

    This example performs sparse matrix-dense matrix multiplication, C = alpha * A * B + beta * C

        //     1 4 0 0 0 0
        // A = 0 2 3 0 0 0
        //     5 0 0 7 8 0
        //     0 0 9 0 6 0

        //     1 4 2
        //     1 2 3
        // B = 5 4 0
        //     3 1 9
        //     1 2 2
        //     0 3 0

        //     1 1 5
        // C = 1 2 1
        //     1 3 1
        //     6 2 4

        rocsparse_int m   = 4;
        rocsparse_int k   = 6;
        rocsparse_int n   = 3;

        csr_row_ptr[m + 1] = {0, 1, 3};                                              // device memory
        csr_col_ind[nnz]   = {0, 0, 1};                                              // device memory
        csr_val[nnz]       = {1, 0, 4, 2, 0, 3, 5, 0, 0, 0, 0, 9, 7, 0, 8, 6, 0, 0}; // device memory

        B[k * n]       = {1, 1, 5, 3, 1, 0, 4, 2, 4, 1, 2, 3, 2, 3, 0, 9, 2, 0};     // device memory
        C[m * n]       = {1, 1, 1, 6, 1, 2, 3, 2, 5, 1, 1, 4};                       // device memory

        rocsparse_int nnz = csr_row_ptr[m] - csr_row_ptr[0];

        float alpha = 1.0f;
        float beta  = 0.0f;

        // Create CSR arrays on device
        rocsparse_int* csr_row_ptr;
        rocsparse_int* csr_col_ind;
        float* csr_val;
        float* B;
        float* C;
        hipMalloc((void**)&csr_row_ptr, sizeof(rocsparse_int) * (m + 1));
        hipMalloc((void**)&csr_col_ind, sizeof(rocsparse_int) * nnz);
        hipMalloc((void**)&csr_val, sizeof(float) * nnz);
        hipMalloc((void**)&B, sizeof(float) * k * n);
        hipMalloc((void**)&C, sizeof(float) * m * n);

        // Create rocsparse handle
        rocsparse_local_handle handle;

        // Types
        rocsparse_indextype itype = rocsparse_indextype_i32;
        rocsparse_indextype jtype = rocsparse_indextype_i32;
        rocsparse_datatype  ttype = rocsparse_datatype_f32_r;

        // Create descriptors
        rocsparse_spmat_descr mat_A;
        rocsparse_dnmat_descr mat_B;
        rocsparse_dnmat_descr mat_C;

        rocsparse_create_csr_descr(&mat_A, m, k, nnz, csr_row_ptr, csr_col_ind, csr_val, itype, jtype, rocsparse_index_base_zero, ttype);
        rocsparse_create_dnmat_descr(&mat_B, k, n, k, B, ttype, rocsparse_order_column);
        rocsparse_create_dnmat_descr(&mat_C, m, n, m, C, ttype, rocsparse_order_column);

        // Query SpMM buffer
        size_t buffer_size;
        rocsparse_spmm(handle,
                       rocsparse_operation_none,
                       rocsparse_operation_none,
                       &alpha,
                       mat_A,
                       mat_B,
                       &beta,
                       mat_C,
                       ttype,
                       rocsparse_spmm_alg_default,
                       rocsparse_spmm_stage_buffer_size,
                       &buffer_size,
                       nullptr));

        // Allocate buffer
        void* buffer;
        hipMalloc(&buffer, buffer_size);

        rocsparse_spmm(handle,
                       rocsparse_operation_none,
                       rocsparse_operation_none,
                       &alpha,
                       mat_A,
                       mat_B,
                       &beta,
                       mat_C,
                       ttype,
                       rocsparse_spmm_alg_default,
                       rocsparse_spmm_stage_preprocess,
                       &buffer_size,
                       buffer));

        // Pointer mode host
        rocsparse_spmm(handle,
                       rocsparse_operation_none,
                       rocsparse_operation_none,
                       &alpha,
                       mat_A,
                       mat_B,
                       &beta,
                       mat_C,
                       ttype,
                       rocsparse_spmm_alg_default,
                       rocsparse_spmm_stage_compute,
                       &buffer_size,
                       buffer));

        // Clear up on device
        hipFree(csr_row_ptr);
        hipFree(csr_col_ind);
        hipFree(csr_val);
        hipFree(B);
        hipFree(C);
        hipFree(temp_buffer);

        rocsparse_destroy_spmat_descr(mat_A);
        rocsparse_destroy_dnmat_descr(mat_B);
        rocsparse_destroy_dnmat_descr(mat_C);

  Example

    SpMM also supports batched computation for CSR and COO matrices. There are three supported batch modes: C_i = A * B_i C_i = A_i * B C_i = A_i * B_i The batch mode is determined by the batch count and stride passed for each matrix. For example to use the first batch mode (C_i = A * B_i) with 100 batches for non-transposed A, B, and C, one passes: batch_count_A = 1 batch_count_B = 100 batch_count_C = 100 offsets_batch_stride_A = 0 columns_values_batch_stride_A = 0 batch_stride_B = k * n batch_stride_C = m * n To use the second batch mode (C_i = A_i * B) one could use: batch_count_A = 100 batch_count_B = 1 batch_count_C = 100 offsets_batch_stride_A = m + 1 columns_values_batch_stride_A = nnz batch_stride_B = 0 batch_stride_C = m * n And to use the third batch mode (C_i = A_i * B_i) one could use: batch_count_A = 100 batch_count_B = 100 batch_count_C = 100 offsets_batch_stride_A = m + 1 columns_values_batch_stride_A = nnz batch_stride_B = k * n batch_stride_C = m * n An example of the first batch mode (C_i = A * B_i) is provided below.

        //     1 4 0 0 0 0
        // A = 0 2 3 0 0 0
        //     5 0 0 7 8 0
        //     0 0 9 0 6 0

        rocsparse_int m   = 4;
        rocsparse_int k   = 6;
        rocsparse_int n   = 3;

        csr_row_ptr[m + 1] = {0, 1, 3};                                              // device memory
        csr_col_ind[nnz]   = {0, 0, 1};                                              // device memory
        csr_val[nnz]       = {1, 0, 4, 2, 0, 3, 5, 0, 0, 0, 0, 9, 7, 0, 8, 6, 0, 0}; // device memory

        B[batch_count_B * k * n]       = {...};     // device memory
        C[batch_count_C * m * n]       = {...};     // device memory

        rocsparse_int nnz = csr_row_ptr[m] - csr_row_ptr[0];

        rocsparse_int batch_count_A = 1;
        rocsparse_int batch_count_B = 100;
        rocsparse_int batch_count_C = 100;

        rocsparse_int offsets_batch_stride_A        = 0;
        rocsparse_int columns_values_batch_stride_A = 0;
        rocsparse_int batch_stride_B                = k * n;
        rocsparse_int batch_stride_C                = m * n;

        float alpha = 1.0f;
        float beta  = 0.0f;

        // Create CSR arrays on device
        rocsparse_int* csr_row_ptr;
        rocsparse_int* csr_col_ind;
        float* csr_val;
        float* B;
        float* C;
        hipMalloc((void**)&csr_row_ptr, sizeof(rocsparse_int) * (m + 1));
        hipMalloc((void**)&csr_col_ind, sizeof(rocsparse_int) * nnz);
        hipMalloc((void**)&csr_val, sizeof(float) * nnz);
        hipMalloc((void**)&B, sizeof(float) * batch_count_B * k * n);
        hipMalloc((void**)&C, sizeof(float) * batch_count_C * m * n);

        // Create rocsparse handle
        rocsparse_local_handle handle;

        // Types
        rocsparse_indextype itype = rocsparse_indextype_i32;
        rocsparse_indextype jtype = rocsparse_indextype_i32;
        rocsparse_datatype  ttype = rocsparse_datatype_f32_r;

        // Create descriptors
        rocsparse_spmat_descr mat_A;
        rocsparse_dnmat_descr mat_B;
        rocsparse_dnmat_descr mat_C;

        rocsparse_create_csr_descr(&mat_A, m, k, nnz, csr_row_ptr, csr_col_ind, csr_val, itype, jtype, rocsparse_index_base_zero, ttype);
        rocsparse_create_dnmat_descr(&mat_B, k, n, k, B, ttype, rocsparse_order_column);
        rocsparse_create_dnmat_descr(&mat_C, m, n, m, C, ttype, rocsparse_order_column);

        rocsparse_csr_set_strided_batch(mat_A, batch_count_A, offsets_batch_stride_A, columns_values_batch_stride_A);
        rocsparse_dnmat_set_strided_batch(B, batch_count_B, batch_stride_B);
        rocsparse_dnmat_set_strided_batch(C, batch_count_C, batch_stride_C);

        // Query SpMM buffer
        size_t buffer_size;
        rocsparse_spmm(handle,
                       rocsparse_operation_none,
                       rocsparse_operation_none,
                       &alpha,
                       mat_A,
                       mat_B,
                       &beta,
                       mat_C,
                       ttype,
                       rocsparse_spmm_alg_default,
                       rocsparse_spmm_stage_buffer_size,
                       &buffer_size,
                       nullptr));

        // Allocate buffer
        void* buffer;
        hipMalloc(&buffer, buffer_size);

        rocsparse_spmm(handle,
                       rocsparse_operation_none,
                       rocsparse_operation_none,
                       &alpha,
                       mat_A,
                       mat_B,
                       &beta,
                       mat_C,
                       ttype,
                       rocsparse_spmm_alg_default,
                       rocsparse_spmm_stage_preprocess,
                       &buffer_size,
                       buffer));

        // Pointer mode host
        rocsparse_spmm(handle,
                       rocsparse_operation_none,
                       rocsparse_operation_none,
                       &alpha,
                       mat_A,
                       mat_B,
                       &beta,
                       mat_C,
                       ttype,
                       rocsparse_spmm_alg_default,
                       rocsparse_spmm_stage_compute,
                       &buffer_size,
                       buffer));

        // Clear up on device
        hipFree(csr_row_ptr);
        hipFree(csr_col_ind);
        hipFree(csr_val);
        hipFree(B);
        hipFree(C);
        hipFree(temp_buffer);

        rocsparse_destroy_spmat_descr(mat_A);
        rocsparse_destroy_dnmat_descr(mat_B);
        rocsparse_destroy_dnmat_descr(mat_C);

  Note

  Only the rocsparse_spmm_stage_buffer_size stage and the rocsparse_spmm_stage_compute stage are non blocking and executed asynchronously with respect to the host. They may return before the actual computation has finished. The rocsparse_spmm_stage_preprocess stage is blocking with respect to the host.

  Note

  Currently, only `trans_A` == rocsparse_operation_none is supported for COO and Blocked ELL formats.

  Note

  Only the rocsparse_spmm_stage_buffer_size stage and the rocsparse_spmm_stage_compute stage support execution in a hipGraph context. The rocsparse_spmm_stage_preprocess stage does not support hipGraph.

  Note

  Currently, only CSR, COO and Blocked ELL sparse formats are supported.

  Note

  Different algorithms are available which can provide better performance for different matrices. Currently, the available algorithms are rocsparse_spmm_alg_csr, rocsparse_spmm_alg_csr_row_split or rocsparse_spmm_alg_csr_merge for CSR matrices, rocsparse_spmm_alg_bell for Blocked ELL matrices and rocsparse_spmm_alg_coo_segmented or rocsparse_spmm_alg_coo_atomic for COO matrices. Additionally, one can specify the algorithm to be rocsparse_spmm_alg_default. In the case of CSR matrices this will set the algorithm to be rocsparse_spmm_alg_csr, in the case of Blocked ELL matrices this will set the algorithm to be rocsparse_spmm_alg_bell and for COO matrices it will set the algorithm to be rocsparse_spmm_alg_coo_atomic. When A is transposed, rocsparse_spmm will revert to using rocsparse_spmm_alg_csr for CSR format and rocsparse_spmm_alg_coo_atomic for COO format regardless of algorithm selected.

  Note

  This function writes the required allocation size (in bytes) to `buffer_size` and returns without performing the SpMM operation, when a nullptr is passed for `temp_buffer`.

  Note

  SpMM requires three stages to complete. The first stage rocsparse_spmm_stage_buffer_size will return the size of the temporary storage buffer that is required for subsequent calls to rocsparse_spmm (or rocsparse_spmm_ex). The second stage rocsparse_spmm_stage_preprocess will preprocess data that would be saved in the temporary storage buffer. In the final stage rocsparse_spmm_stage_compute, the actual computation is performed.

  Note

  If rocsparse_spmm_stage_auto is selected, rocSPARSE will automatically detect which stage is required based on the following indicators: If `temp_buffer` is equal to `nullptr`, the required buffer size will be returned. Else, the SpMM preprocess and the SpMM algorithm will be executed.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - trans_A – [in] matrix operation type.

    - trans_B – [in] matrix operation type.

    - alpha – [in] scalar \(\alpha\).

    - mat_A – [in] matrix descriptor.

    - mat_B – [in] matrix descriptor.

    - beta – [in] scalar \(\beta\).

    - mat_C – [in] matrix descriptor.

    - compute_type – [in] floating point precision for the SpMM computation.

    - alg – [in] SpMM algorithm for the SpMM computation.

    - stage – [in] SpMM stage for the SpMM computation.

    - buffer_size – [out] number of bytes of the temporary storage buffer. buffer_size is set when `temp_buffer` is nullptr.

    - temp_buffer – [in] temporary storage buffer allocated by the user. When a nullptr is passed, the required allocation size (in bytes) is written to `buffer_size` and function returns without performing the SpMM operation.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_pointer – `alpha`, `mat_A`, `mat_B`, `mat_C`, `beta`, or `buffer_size` pointer is invalid.

    - rocsparse_status_not_implemented – `trans_A`, `trans_B`, `compute_type` or `alg` is currently not supported.

### rocsparse_spmm_ex()

rocsparse_status rocsparse_spmm_ex(rocsparse_handle handle, rocsparse_operation trans_A, rocsparse_operation trans_B, const void *alpha, const rocsparse_spmat_descr mat_A, const rocsparse_dnmat_descr mat_B, const void *beta, const rocsparse_dnmat_descr mat_C, rocsparse_datatype compute_type, rocsparse_spmm_alg alg, rocsparse_spmm_stage stage, size_t *buffer_size, void *temp_buffer)

  Sparse matrix dense matrix multiplication, extension routine.

  `rocsparse_spmm` (or `rocsparse_spmm_ex` ) multiplies the scalar \(\alpha\) with a sparse \(m \times k\) matrix \(A\), defined in CSR or COO or Blocked ELL storage format, and the dense \(k \times n\) matrix \(B\) and adds the result to the dense \(m \times n\) matrix \(C\) that is multiplied by the scalar \(\beta\), such that

  \[ C := \alpha \cdot op(A) \cdot op(B) + \beta \cdot C, \]
  with
  \[\begin{split} op(A) = \left\{ \begin{array}{ll} A, & \text{if trans_A == rocsparse_operation_none} \\ A^T, & \text{if trans_A == rocsparse_operation_transpose} \\ A^H, & \text{if trans_A == rocsparse_operation_conjugate_transpose} \end{array} \right. \end{split}\]
  and
  \[\begin{split} op(B) = \left\{ \begin{array}{ll} B, & \text{if trans_B == rocsparse_operation_none} \\ B^T, & \text{if trans_B == rocsparse_operation_transpose} \\ B^H, & \text{if trans_B == rocsparse_operation_conjugate_transpose} \end{array} \right. \end{split}\]

  Example

    This example performs sparse matrix-dense matrix multiplication, C = alpha * A * B + beta * C

        //     1 4 0 0 0 0
        // A = 0 2 3 0 0 0
        //     5 0 0 7 8 0
        //     0 0 9 0 6 0

        //     1 4 2
        //     1 2 3
        // B = 5 4 0
        //     3 1 9
        //     1 2 2
        //     0 3 0

        //     1 1 5
        // C = 1 2 1
        //     1 3 1
        //     6 2 4

        rocsparse_int m   = 4;
        rocsparse_int k   = 6;
        rocsparse_int n   = 3;

        csr_row_ptr[m + 1] = {0, 1, 3};                                              // device memory
        csr_col_ind[nnz]   = {0, 0, 1};                                              // device memory
        csr_val[nnz]       = {1, 0, 4, 2, 0, 3, 5, 0, 0, 0, 0, 9, 7, 0, 8, 6, 0, 0}; // device memory

        B[k * n]       = {1, 1, 5, 3, 1, 0, 4, 2, 4, 1, 2, 3, 2, 3, 0, 9, 2, 0};     // device memory
        C[m * n]       = {1, 1, 1, 6, 1, 2, 3, 2, 5, 1, 1, 4};                       // device memory

        rocsparse_int nnz = csr_row_ptr[m] - csr_row_ptr[0];

        float alpha = 1.0f;
        float beta  = 0.0f;

        // Create CSR arrays on device
        rocsparse_int* csr_row_ptr;
        rocsparse_int* csr_col_ind;
        float* csr_val;
        float* B;
        float* C;
        hipMalloc((void**)&csr_row_ptr, sizeof(rocsparse_int) * (m + 1));
        hipMalloc((void**)&csr_col_ind, sizeof(rocsparse_int) * nnz);
        hipMalloc((void**)&csr_val, sizeof(float) * nnz);
        hipMalloc((void**)&B, sizeof(float) * k * n);
        hipMalloc((void**)&C, sizeof(float) * m * n);

        // Create rocsparse handle
        rocsparse_local_handle handle;

        // Types
        rocsparse_indextype itype = rocsparse_indextype_i32;
        rocsparse_indextype jtype = rocsparse_indextype_i32;
        rocsparse_datatype  ttype = rocsparse_datatype_f32_r;

        // Create descriptors
        rocsparse_spmat_descr mat_A;
        rocsparse_dnmat_descr mat_B;
        rocsparse_dnmat_descr mat_C;

        rocsparse_create_csr_descr(&mat_A, m, k, nnz, csr_row_ptr, csr_col_ind, csr_val, itype, jtype, rocsparse_index_base_zero, ttype);
        rocsparse_create_dnmat_descr(&mat_B, k, n, k, B, ttype, rocsparse_order_column);
        rocsparse_create_dnmat_descr(&mat_C, m, n, m, C, ttype, rocsparse_order_column);

        // Query SpMM buffer
        size_t buffer_size;
        rocsparse_spmm(handle,
                       rocsparse_operation_none,
                       rocsparse_operation_none,
                       &alpha,
                       mat_A,
                       mat_B,
                       &beta,
                       mat_C,
                       ttype,
                       rocsparse_spmm_alg_default,
                       rocsparse_spmm_stage_buffer_size,
                       &buffer_size,
                       nullptr));

        // Allocate buffer
        void* buffer;
        hipMalloc(&buffer, buffer_size);

        rocsparse_spmm(handle,
                       rocsparse_operation_none,
                       rocsparse_operation_none,
                       &alpha,
                       mat_A,
                       mat_B,
                       &beta,
                       mat_C,
                       ttype,
                       rocsparse_spmm_alg_default,
                       rocsparse_spmm_stage_preprocess,
                       &buffer_size,
                       buffer));

        // Pointer mode host
        rocsparse_spmm(handle,
                       rocsparse_operation_none,
                       rocsparse_operation_none,
                       &alpha,
                       mat_A,
                       mat_B,
                       &beta,
                       mat_C,
                       ttype,
                       rocsparse_spmm_alg_default,
                       rocsparse_spmm_stage_compute,
                       &buffer_size,
                       buffer));

        // Clear up on device
        hipFree(csr_row_ptr);
        hipFree(csr_col_ind);
        hipFree(csr_val);
        hipFree(B);
        hipFree(C);
        hipFree(temp_buffer);

        rocsparse_destroy_spmat_descr(mat_A);
        rocsparse_destroy_dnmat_descr(mat_B);
        rocsparse_destroy_dnmat_descr(mat_C);

  Example

    SpMM also supports batched computation for CSR and COO matrices. There are three supported batch modes: C_i = A * B_i C_i = A_i * B C_i = A_i * B_i The batch mode is determined by the batch count and stride passed for each matrix. For example to use the first batch mode (C_i = A * B_i) with 100 batches for non-transposed A, B, and C, one passes: batch_count_A = 1 batch_count_B = 100 batch_count_C = 100 offsets_batch_stride_A = 0 columns_values_batch_stride_A = 0 batch_stride_B = k * n batch_stride_C = m * n To use the second batch mode (C_i = A_i * B) one could use: batch_count_A = 100 batch_count_B = 1 batch_count_C = 100 offsets_batch_stride_A = m + 1 columns_values_batch_stride_A = nnz batch_stride_B = 0 batch_stride_C = m * n And to use the third batch mode (C_i = A_i * B_i) one could use: batch_count_A = 100 batch_count_B = 100 batch_count_C = 100 offsets_batch_stride_A = m + 1 columns_values_batch_stride_A = nnz batch_stride_B = k * n batch_stride_C = m * n An example of the first batch mode (C_i = A * B_i) is provided below.

        //     1 4 0 0 0 0
        // A = 0 2 3 0 0 0
        //     5 0 0 7 8 0
        //     0 0 9 0 6 0

        rocsparse_int m   = 4;
        rocsparse_int k   = 6;
        rocsparse_int n   = 3;

        csr_row_ptr[m + 1] = {0, 1, 3};                                              // device memory
        csr_col_ind[nnz]   = {0, 0, 1};                                              // device memory
        csr_val[nnz]       = {1, 0, 4, 2, 0, 3, 5, 0, 0, 0, 0, 9, 7, 0, 8, 6, 0, 0}; // device memory

        B[batch_count_B * k * n]       = {...};     // device memory
        C[batch_count_C * m * n]       = {...};     // device memory

        rocsparse_int nnz = csr_row_ptr[m] - csr_row_ptr[0];

        rocsparse_int batch_count_A = 1;
        rocsparse_int batch_count_B = 100;
        rocsparse_int batch_count_C = 100;

        rocsparse_int offsets_batch_stride_A        = 0;
        rocsparse_int columns_values_batch_stride_A = 0;
        rocsparse_int batch_stride_B                = k * n;
        rocsparse_int batch_stride_C                = m * n;

        float alpha = 1.0f;
        float beta  = 0.0f;

        // Create CSR arrays on device
        rocsparse_int* csr_row_ptr;
        rocsparse_int* csr_col_ind;
        float* csr_val;
        float* B;
        float* C;
        hipMalloc((void**)&csr_row_ptr, sizeof(rocsparse_int) * (m + 1));
        hipMalloc((void**)&csr_col_ind, sizeof(rocsparse_int) * nnz);
        hipMalloc((void**)&csr_val, sizeof(float) * nnz);
        hipMalloc((void**)&B, sizeof(float) * batch_count_B * k * n);
        hipMalloc((void**)&C, sizeof(float) * batch_count_C * m * n);

        // Create rocsparse handle
        rocsparse_local_handle handle;

        // Types
        rocsparse_indextype itype = rocsparse_indextype_i32;
        rocsparse_indextype jtype = rocsparse_indextype_i32;
        rocsparse_datatype  ttype = rocsparse_datatype_f32_r;

        // Create descriptors
        rocsparse_spmat_descr mat_A;
        rocsparse_dnmat_descr mat_B;
        rocsparse_dnmat_descr mat_C;

        rocsparse_create_csr_descr(&mat_A, m, k, nnz, csr_row_ptr, csr_col_ind, csr_val, itype, jtype, rocsparse_index_base_zero, ttype);
        rocsparse_create_dnmat_descr(&mat_B, k, n, k, B, ttype, rocsparse_order_column);
        rocsparse_create_dnmat_descr(&mat_C, m, n, m, C, ttype, rocsparse_order_column);

        rocsparse_csr_set_strided_batch(mat_A, batch_count_A, offsets_batch_stride_A, columns_values_batch_stride_A);
        rocsparse_dnmat_set_strided_batch(B, batch_count_B, batch_stride_B);
        rocsparse_dnmat_set_strided_batch(C, batch_count_C, batch_stride_C);

        // Query SpMM buffer
        size_t buffer_size;
        rocsparse_spmm(handle,
                       rocsparse_operation_none,
                       rocsparse_operation_none,
                       &alpha,
                       mat_A,
                       mat_B,
                       &beta,
                       mat_C,
                       ttype,
                       rocsparse_spmm_alg_default,
                       rocsparse_spmm_stage_buffer_size,
                       &buffer_size,
                       nullptr));

        // Allocate buffer
        void* buffer;
        hipMalloc(&buffer, buffer_size);

        rocsparse_spmm(handle,
                       rocsparse_operation_none,
                       rocsparse_operation_none,
                       &alpha,
                       mat_A,
                       mat_B,
                       &beta,
                       mat_C,
                       ttype,
                       rocsparse_spmm_alg_default,
                       rocsparse_spmm_stage_preprocess,
                       &buffer_size,
                       buffer));

        // Pointer mode host
        rocsparse_spmm(handle,
                       rocsparse_operation_none,
                       rocsparse_operation_none,
                       &alpha,
                       mat_A,
                       mat_B,
                       &beta,
                       mat_C,
                       ttype,
                       rocsparse_spmm_alg_default,
                       rocsparse_spmm_stage_compute,
                       &buffer_size,
                       buffer));

        // Clear up on device
        hipFree(csr_row_ptr);
        hipFree(csr_col_ind);
        hipFree(csr_val);
        hipFree(B);
        hipFree(C);
        hipFree(temp_buffer);

        rocsparse_destroy_spmat_descr(mat_A);
        rocsparse_destroy_dnmat_descr(mat_B);
        rocsparse_destroy_dnmat_descr(mat_C);

  Note

  Only the rocsparse_spmm_stage_buffer_size stage and the rocsparse_spmm_stage_compute stage are non blocking and executed asynchronously with respect to the host. They may return before the actual computation has finished. The rocsparse_spmm_stage_preprocess stage is blocking with respect to the host.

  Note

  Currently, only `trans_A` == rocsparse_operation_none is supported for COO and Blocked ELL formats.

  Note

  Only the rocsparse_spmm_stage_buffer_size stage and the rocsparse_spmm_stage_compute stage support execution in a hipGraph context. The rocsparse_spmm_stage_preprocess stage does not support hipGraph.

  Note

  Currently, only CSR, COO and Blocked ELL sparse formats are supported.

  Note

  Different algorithms are available which can provide better performance for different matrices. Currently, the available algorithms are rocsparse_spmm_alg_csr, rocsparse_spmm_alg_csr_row_split or rocsparse_spmm_alg_csr_merge for CSR matrices, rocsparse_spmm_alg_bell for Blocked ELL matrices and rocsparse_spmm_alg_coo_segmented or rocsparse_spmm_alg_coo_atomic for COO matrices. Additionally, one can specify the algorithm to be rocsparse_spmm_alg_default. In the case of CSR matrices this will set the algorithm to be rocsparse_spmm_alg_csr, in the case of Blocked ELL matrices this will set the algorithm to be rocsparse_spmm_alg_bell and for COO matrices it will set the algorithm to be rocsparse_spmm_alg_coo_atomic. When A is transposed, rocsparse_spmm will revert to using rocsparse_spmm_alg_csr for CSR format and rocsparse_spmm_alg_coo_atomic for COO format regardless of algorithm selected.

  Note

  This function writes the required allocation size (in bytes) to `buffer_size` and returns without performing the SpMM operation, when a nullptr is passed for `temp_buffer`.

  Note

  SpMM requires three stages to complete. The first stage rocsparse_spmm_stage_buffer_size will return the size of the temporary storage buffer that is required for subsequent calls to rocsparse_spmm (or rocsparse_spmm_ex). The second stage rocsparse_spmm_stage_preprocess will preprocess data that would be saved in the temporary storage buffer. In the final stage rocsparse_spmm_stage_compute, the actual computation is performed.

  Note

  If rocsparse_spmm_stage_auto is selected, rocSPARSE will automatically detect which stage is required based on the following indicators: If `temp_buffer` is equal to `nullptr`, the required buffer size will be returned. Else, the SpMM preprocess and the SpMM algorithm will be executed.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - trans_A – [in] matrix operation type.

    - trans_B – [in] matrix operation type.

    - alpha – [in] scalar \(\alpha\).

    - mat_A – [in] matrix descriptor.

    - mat_B – [in] matrix descriptor.

    - beta – [in] scalar \(\beta\).

    - mat_C – [in] matrix descriptor.

    - compute_type – [in] floating point precision for the SpMM computation.

    - alg – [in] SpMM algorithm for the SpMM computation.

    - stage – [in] SpMM stage for the SpMM computation.

    - buffer_size – [out] number of bytes of the temporary storage buffer. buffer_size is set when `temp_buffer` is nullptr.

    - temp_buffer – [in] temporary storage buffer allocated by the user. When a nullptr is passed, the required allocation size (in bytes) is written to `buffer_size` and function returns without performing the SpMM operation.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_pointer – `alpha`, `mat_A`, `mat_B`, `mat_C`, `beta`, or `buffer_size` pointer is invalid.

    - rocsparse_status_not_implemented – `trans_A`, `trans_B`, `compute_type` or `alg` is currently not supported.

### rocsparse_spgemm()

rocsparse_status rocsparse_spgemm(rocsparse_handle handle, rocsparse_operation trans_A, rocsparse_operation trans_B, const void *alpha, const rocsparse_spmat_descr A, const rocsparse_spmat_descr B, const void *beta, const rocsparse_spmat_descr D, rocsparse_spmat_descr C, rocsparse_datatype compute_type, rocsparse_spgemm_alg alg, rocsparse_spgemm_stage stage, size_t *buffer_size, void *temp_buffer)

  Sparse matrix sparse matrix multiplication.

  rocsparse_spgemm multiplies the scalar \(\alpha\) with the sparse \(m \times k\) matrix \(A\) and the sparse \(k \times n\) matrix \(B\) and adds the result to the sparse \(m \times n\) matrix \(D\) that is multiplied by \(\beta\). The final result is stored in the sparse \(m \times n\) matrix \(C\), such that

  \[ C := \alpha \cdot op(A) \cdot op(B) + \beta \cdot D, \]
  with
  \[\begin{split} op(A) = \left\{ \begin{array}{ll} A, & \text{if trans_A == rocsparse_operation_none} \\ A^T, & \text{if trans_A == rocsparse_operation_transpose} \\ A^H, & \text{if trans_A == rocsparse_operation_conjugate_transpose} \end{array} \right. \end{split}\]
  and
  \[\begin{split} op(B) = \left\{ \begin{array}{ll} B, & \text{if trans_B == rocsparse_operation_none} \\ B^T, & \text{if trans_B == rocsparse_operation_transpose} \\ B^H, & \text{if trans_B == rocsparse_operation_conjugate_transpose} \end{array} \right. \end{split}\]

  Note

  SpGEMM requires three stages to complete. The first stage rocsparse_spgemm_stage_buffer_size will return the size of the temporary storage buffer that is required for subsequent calls to rocsparse_spgemm. The second stage rocsparse_spgemm_stage_nnz will determine the number of non-zero elements of the resulting \(C\) matrix. If the sparsity pattern of \(C\) is already known, this stage can be skipped. In the final stage rocsparse_spgemm_stage_compute, the actual computation is performed.

  Note

  If rocsparse_spgemm_stage_auto is selected, rocSPARSE will automatically detect which stage is required based on the following indicators: If `temp_buffer` is equal to `nullptr`, the required buffer size will be returned. Else, if the number of non-zeros of \(C\) is zero, the number of non-zero entries will be computed. Else, the SpGEMM algorithm will be executed.

  Note

  If \(\alpha == 0\), then \(C = \beta \cdot D\) will be computed.

  Note

  If \(\beta == 0\), then \(C = \alpha \cdot op(A) \cdot op(B)\) will be computed.

  Note

  Currently only CSR and BSR formats are supported.

  Note

  If rocsparse_spgemm_stage_symbolic is selected then the symbolic computation is performed only.

  Note

  If rocsparse_spgemm_stage_numeric is selected then the numeric computation is performed only.

  Note

  For the rocsparse_spgemm_stage_symbolic and rocsparse_spgemm_stage_numeric stages, only CSR matrix format is currently supported.

  Note

  \(\alpha == beta == 0\) is invalid.

  Note

  It is allowed to pass the same sparse matrix for \(C\) and \(D\), if both matrices have the same sparsity pattern.

  Note

  Currently, only `trans_A` == rocsparse_operation_none is supported.

  Note

  Currently, only `trans_B` == rocsparse_operation_none is supported.

  Note

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

  Note

  Please note, that for rare matrix products with more than 4096 non-zero entries per row, additional temporary storage buffer is allocated by the algorithm.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - trans_A – [in] sparse matrix \(A\) operation type.

    - trans_B – [in] sparse matrix \(B\) operation type.

    - alpha – [in] scalar \(\alpha\).

    - A – [in] sparse matrix \(A\) descriptor.

    - B – [in] sparse matrix \(B\) descriptor.

    - beta – [in] scalar \(\beta\).

    - D – [in] sparse matrix \(D\) descriptor.

    - C – [out] sparse matrix \(C\) descriptor.

    - compute_type – [in] floating point precision for the SpGEMM computation.

    - alg – [in] SpGEMM algorithm for the SpGEMM computation.

    - stage – [in] SpGEMM stage for the SpGEMM computation.

    - buffer_size – [out] number of bytes of the temporary storage buffer. buffer_size is set when `temp_buffer` is nullptr.

    - temp_buffer – [in] temporary storage buffer allocated by the user. When a nullptr is passed, the required allocation size (in bytes) is written to `buffer_size` and function returns without performing the SpGEMM operation.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_pointer – `alpha` and `beta` are invalid, `A`, `B`, `D`, `C` or `buffer_size` pointer is invalid.

    - rocsparse_status_memory_error – additional buffer for long rows could not be allocated.

    - rocsparse_status_not_implemented – `trans_A` != rocsparse_operation_none or `trans_B` != rocsparse_operation_none.

### rocsparse_sddmm_buffer_size()

rocsparse_status rocsparse_sddmm_buffer_size(rocsparse_handle handle, rocsparse_operation opA, rocsparse_operation opB, const void *alpha, const rocsparse_dnmat_descr A, const rocsparse_dnmat_descr B, const void *beta, rocsparse_spmat_descr C, rocsparse_datatype compute_type, rocsparse_sddmm_alg alg, size_t *buffer_size)

  Calculate the size in bytes of the required buffer for the use of rocsparse_sddmm and rocsparse_sddmm_preprocess.

  rocsparse_sddmm_buffer_size returns the size of the required buffer to execute the SDDMM operation from a given configuration.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - opA – [in] dense matrix \(A\) operation type.

    - opB – [in] dense matrix \(B\) operation type.

    - alpha – [in] scalar \(\alpha\).

    - A – [in] dense matrix \(A\) descriptor.

    - B – [in] dense matrix \(B\) descriptor.

    - beta – [in] scalar \(\beta\).

    - C – [inout] sparse matrix \(C\) descriptor.

    - compute_type – [in] floating point precision for the SDDMM computation.

    - alg – [in] specification of the algorithm to use.

    - buffer_size – [out] number of bytes of the temporary storage buffer.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_value – the value of `trans_A` or `trans_B` is incorrect.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_pointer – `alpha` and `beta` are invalid, `A`, `B`, `D`, `C` or `buffer_size` pointer is invalid.

    - rocsparse_status_not_implemented – `opA` == rocsparse_operation_conjugate_transpose or `opB` == rocsparse_operation_conjugate_transpose.

### rocsparse_sddmm_preprocess()

rocsparse_status rocsparse_sddmm_preprocess(rocsparse_handle handle, rocsparse_operation opA, rocsparse_operation opB, const void *alpha, const rocsparse_dnmat_descr A, const rocsparse_dnmat_descr B, const void *beta, rocsparse_spmat_descr C, rocsparse_datatype compute_type, rocsparse_sddmm_alg alg, void *temp_buffer)

  Preprocess data before the use of rocsparse_sddmm.

  rocsparse_sddmm_preprocess executes a part of the algorithm that can be calculated once in the context of multiple calls of the rocsparse_sddmm with the same sparsity pattern.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - opA – [in] dense matrix \(A\) operation type.

    - opB – [in] dense matrix \(B\) operation type.

    - alpha – [in] scalar \(\alpha\).

    - A – [in] dense matrix \(A\) descriptor.

    - B – [in] dense matrix \(B\) descriptor.

    - beta – [in] scalar \(\beta\).

    - C – [inout] sparse matrix \(C\) descriptor.

    - compute_type – [in] floating point precision for the SDDMM computation.

    - alg – [in] specification of the algorithm to use.

    - temp_buffer – [in] temporary storage buffer allocated by the user. The size must be greater or equal to the size obtained with rocsparse_sddmm_buffer_size.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_value – the value of `trans_A` or `trans_B` is incorrect.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_pointer – `alpha` and `beta` are invalid, `A`, `B`, `D`, `C` or `temp_buffer` pointer is invalid.

    - rocsparse_status_not_implemented – `opA` == rocsparse_operation_conjugate_transpose or `opB` == rocsparse_operation_conjugate_transpose.

### rocsparse_sddmm()

rocsparse_status rocsparse_sddmm(rocsparse_handle handle, rocsparse_operation opA, rocsparse_operation opB, const void *alpha, const rocsparse_dnmat_descr A, const rocsparse_dnmat_descr B, const void *beta, rocsparse_spmat_descr C, rocsparse_datatype compute_type, rocsparse_sddmm_alg alg, void *temp_buffer)

  Sampled Dense-Dense Matrix Multiplication.

  rocsparse_sddmm multiplies the scalar \(\alpha\) with the dense \(m \times k\) matrix \(A\), the dense \(k \times n\) matrix \(B\), filtered by the sparsity pattern of the \(m \times n\) sparse matrix \(C\) and adds the result to \(C\) scaled by \(\beta\). The final result is stored in the sparse \(m \times n\) matrix \(C\), such that

  \[ C := \alpha ( opA(A) \cdot opB(B) ) \cdot spy(C) + \beta C, \]
  with
  \[\begin{split} op(A) = \left\{ \begin{array}{ll} A, & \text{if opA == rocsparse_operation_none} \\ A^T, & \text{if opA == rocsparse_operation_transpose} \\ \end{array} \right. \end{split}\]
  ,
  \[\begin{split} op(B) = \left\{ \begin{array}{ll} B, & \text{if opB == rocsparse_operation_none} \\ B^T, & \text{if opB == rocsparse_operation_transpose} \\ \end{array} \right. \end{split}\]
  and
  \[\begin{split} spy(C)_ij = \left\{ \begin{array}{ll} 1 \text{if i == j}, & 0 \text{if i != j} \\ \end{array} \right. \end{split}\]

  Note

  `opA` == rocsparse_operation_conjugate_transpose is not supported.

  Note

  `opB` == rocsparse_operation_conjugate_transpose is not supported.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - opA – [in] dense matrix \(A\) operation type.

    - opB – [in] dense matrix \(B\) operation type.

    - alpha – [in] scalar \(\alpha\).

    - A – [in] dense matrix \(A\) descriptor.

    - B – [in] dense matrix \(B\) descriptor.

    - beta – [in] scalar \(\beta\).

    - C – [inout] sparse matrix \(C\) descriptor.

    - compute_type – [in] floating point precision for the SDDMM computation.

    - alg – [in] specification of the algorithm to use.

    - temp_buffer – [in] temporary storage buffer allocated by the user. The size must be greater or equal to the size obtained with rocsparse_sddmm_buffer_size.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_value – the value of `trans_A`, `trans_B`, `compute_type` or alg is incorrect.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_pointer – `alpha` and `beta` are invalid, `A`, `B`, `D`, `C` or `temp_buffer` pointer is invalid.

    - rocsparse_status_not_implemented – `opA` == rocsparse_operation_conjugate_transpose or `opB` == rocsparse_operation_conjugate_transpose.

### rocsparse_dense_to_sparse()

rocsparse_status rocsparse_dense_to_sparse(rocsparse_handle handle, const rocsparse_dnmat_descr mat_A, rocsparse_spmat_descr mat_B, rocsparse_dense_to_sparse_alg alg, size_t *buffer_size, void *temp_buffer)

  Dense matrix to sparse matrix conversion.

  `rocsparse_dense_to_sparse` `rocsparse_dense_to_sparse` performs the conversion of a dense matrix to a sparse matrix in CSR, CSC, or COO format.

  Note

  This function writes the required allocation size (in bytes) to `buffer_size` and returns without performing the dense to sparse operation, when a nullptr is passed for `temp_buffer`.

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - mat_A – [in] dense matrix descriptor.

    - mat_B – [in] sparse matrix descriptor.

    - alg – [in] algorithm for the sparse to dense computation.

    - buffer_size – [out] number of bytes of the temporary storage buffer. buffer_size is set when `temp_buffer` is nullptr.

    - temp_buffer – [in] temporary storage buffer allocated by the user. When a nullptr is passed, the required allocation size (in bytes) is written to `buffer_size` and function returns without performing the dense to sparse operation.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_pointer – `mat_A`, `mat_B`, or `buffer_size` pointer is invalid.

### rocsparse_sparse_to_dense()

rocsparse_status rocsparse_sparse_to_dense(rocsparse_handle handle, const rocsparse_spmat_descr mat_A, rocsparse_dnmat_descr mat_B, rocsparse_sparse_to_dense_alg alg, size_t *buffer_size, void *temp_buffer)

  Sparse matrix to dense matrix conversion.

  `rocsparse_sparse_to_dense` `rocsparse_sparse_to_dense` performs the conversion of a sparse matrix in CSR, CSC, or COO format to a dense matrix

  Note

  This function writes the required allocation size (in bytes) to `buffer_size` and returns without performing the sparse to dense operation, when a nullptr is passed for `temp_buffer`.

  Note

  This function is blocking with respect to the host.

  Note

  This routine does not support execution in a hipGraph context.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - mat_A – [in] sparse matrix descriptor.

    - mat_B – [in] dense matrix descriptor.

    - alg – [in] algorithm for the sparse to dense computation.

    - buffer_size – [out] number of bytes of the temporary storage buffer. buffer_size is set when `temp_buffer` is nullptr.

    - temp_buffer – [in] temporary storage buffer allocated by the user. When a nullptr is passed, the required allocation size (in bytes) is written to `buffer_size` and function returns without performing the sparse to dense operation.

  Return values:

    - rocsparse_status_success – the operation completed successfully.

    - rocsparse_status_invalid_handle – the library context was not initialized.

    - rocsparse_status_invalid_pointer – `mat_A`, `mat_B`, or `buffer_size` pointer is invalid.