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: 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
CMake 3.5 or later
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#
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
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 |
coo_row_ind |
array of |
coo_col_ind |
array of |
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:
where
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 |
coo_ind |
array of |
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:
where
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 |
csr_row_ptr |
array of |
csr_col_ind |
array of |
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:
where
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 |
csc_col_ptr |
array of |
csc_row_ind |
array of |
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:
where
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 |
bsr_row_ptr |
array of |
bsr_col_ind |
array of |
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:
with the blocks \(A_{ij}\)
such that
with arrays representation
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 |
bsr_row_ptr |
array of |
bsr_col_ind |
array of |
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:
with the blocks \(A_{ij}\)
such that
with arrays representation
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 |
ell_col_ind |
array of |
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:
where
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 |
ell_col_ind |
array of |
coo_val |
array of |
coo_row_ind |
array of |
coo_col_ind |
array of |
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.
-
enumerator rocsparse_action_symbolic#
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.
-
enumerator rocsparse_direction_row#
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.
-
enumerator rocsparse_hyb_partition_auto#
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.
-
enumerator rocsparse_index_base_zero#
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.
-
enumerator rocsparse_matrix_type_general#
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.
-
enumerator rocsparse_fill_mode_lower#
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.
-
enumerator rocsparse_storage_mode_sorted#
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
-
enumerator rocsparse_diag_type_non_unit#
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.
-
enumerator rocsparse_operation_none#
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.
-
enumerator rocsparse_pointer_mode_host#
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.
-
enumerator rocsparse_analysis_policy_reuse#
rocsparse_solve_policy#
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.
-
enumerator rocsparse_layer_mode_none#
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_success#
rocsparse_indextype#
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
-
enumerator rocsparse_datatype_f32_r#
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.
-
enumerator rocsparse_format_coo#
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.
-
enumerator rocsparse_order_row#
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.
-
enumerator rocsparse_spmv_alg_default#
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.
-
enumerator rocsparse_spmv_stage_auto#
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.
-
enumerator rocsparse_spsv_alg_default#
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.
-
enumerator rocsparse_spsv_stage_auto#
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.
-
enumerator rocsparse_spsm_alg_default#
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.
-
enumerator rocsparse_spsm_stage_auto#
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.
-
enumerator rocsparse_spmm_alg_default#
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.
-
enumerator rocsparse_spmm_stage_auto#
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.
-
enumerator rocsparse_sddmm_alg_default#
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.
-
enumerator rocsparse_spgemm_stage_auto#
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.
-
enumerator rocsparse_spgemm_alg_default#
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.
-
enumerator rocsparse_sparse_to_dense_alg_default#
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.
-
enumerator rocsparse_dense_to_sparse_alg_default#
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).
-
enumerator rocsparse_gtsv_interleaved_alg_default#
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:
|
logging is disabled. |
|
trace logging is enabled. |
|
bench logging is enabled. |
|
trace logging and bench logging is enabled. |
|
debug logging is enabled. |
|
trace logging and debug logging is enabled. |
|
bench logging and debug logging is enabled. |
|
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 |
Sparse Level 1 Functions#
Function name |
single |
double |
single complex |
double complex |
---|---|---|---|---|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
|||
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
|||
x |
x |
x |
x |
Sparse Level 2 Functions#
Function name |
single |
double |
single complex |
double complex |
---|---|---|---|---|
x |
x |
x |
x |
|
|
||||
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
Sparse Level 3 Functions#
Function name |
single |
double |
single complex |
double complex |
---|---|---|---|---|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
Sparse Extra Functions#
Function name |
single |
double |
single complex |
double complex |
---|---|---|---|---|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
|
||||
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
Preconditioner Functions#
Function name |
single |
double |
single complex |
double complex |
---|---|---|---|---|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
Conversion Functions#
Function name |
single |
double |
single complex |
double complex |
---|---|---|---|---|
x |
x |
x |
x |
|
|
x |
x |
x |
x |
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
|||
x |
x |
|||
x |
x |
|||
x |
x |
|||
x |
x |
|||
x |
x |
|||
x |
x |
|||
x |
x |
|||
x |
x |
|||
x |
x |
|||
x |
x |
|||
x |
x |
|||
x |
x |
x |
x |
Reordering Functions#
Function name |
single |
double |
single complex |
double complex |
---|---|---|---|---|
x |
x |
x |
x |
Utility Functions#
Function name |
single |
double |
single complex |
double complex |
---|---|---|---|---|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
Sparse Generic Functions#
Function name |
single |
double |
single complex |
double complex |
---|---|---|---|---|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
x |
x |
x |
x |
|
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:
Scaling parameters, such as alpha and beta used in e.g.
rocsparse_scsrmv()
,rocsparse_scoomv()
, …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 orrocsparse_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 callingrocsparse_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
ordest
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_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_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_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 inHYB
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 aHYB
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 callingrocsparse_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 callingrocsparse_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
ordest
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 callingrocsparse_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
ordest
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
orindices
orvalues
is invalid.rocsparse_status_invalid_size – if
size
ornnz
is invalid.rocsparse_status_invalid_value – if
idx_type
oridx_base
ordata_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
orindices
orvalues
is invalid.rocsparse_status_invalid_size – if
size
ornnz
is invalid.rocsparse_status_invalid_value – if
idx_type
oridx_base
ordata_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
orvalues
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
orvalues
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 usingrocsparse_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
orcoo_row_ind
orcoo_col_ind
orcoo_val
is invalid.rocsparse_status_invalid_size – if
rows
orcols
ornnz
is invalid.rocsparse_status_invalid_value – if
idx_type
oridx_base
ordata_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 usingrocsparse_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
orcoo_ind
orcoo_val
is invalid.rocsparse_status_invalid_size – if
rows
orcols
ornnz
is invalid.rocsparse_status_invalid_value – if
idx_type
oridx_base
ordata_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 usingrocsparse_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
orcsr_row_ptr
orcsr_col_ind
orcsr_val
is invalid.rocsparse_status_invalid_size – if
rows
orcols
ornnz
is invalid.rocsparse_status_invalid_value – if
row_ptr_type
orcol_ind_type
oridx_base
ordata_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 usingrocsparse_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
orcsc_col_ptr
orcsc_row_ind
orcsc_val
is invalid.rocsparse_status_invalid_size – if
rows
orcols
ornnz
is invalid.rocsparse_status_invalid_value – if
col_ptr_type
orrow_ind_type
oridx_base
ordata_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 usingrocsparse_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
orell_col_ind
orell_val
is invalid.rocsparse_status_invalid_size – if
rows
orcols
orell_width
is invalid.rocsparse_status_invalid_value – if
idx_type
oridx_base
ordata_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 usingrocsparse_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
orell_cols
orell_col_ind
orell_val
is invalid.rocsparse_status_invalid_size – if
rows
orcols
is invalid.rocsparse_status_invalid_value – if
idx_type
oridx_base
ordata_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
orcoo_row_ind
orcoo_col_ind
orcoo_val
is invalid.rocsparse_status_invalid_size – if
rows
orcols
ornnz
is invalid.rocsparse_status_invalid_value – if
idx_type
oridx_base
ordata_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
orcoo_ind
orcoo_val
is invalid.rocsparse_status_invalid_size – if
rows
orcols
ornnz
is invalid.rocsparse_status_invalid_value – if
idx_type
oridx_base
ordata_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
orcsr_row_ptr
orcsr_col_ind
orcsr_val
is invalid.rocsparse_status_invalid_size – if
rows
orcols
ornnz
is invalid.rocsparse_status_invalid_value – if
row_ptr_type
orcol_ind_type
oridx_base
ordata_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
orell_col_ind
orell_val
is invalid.rocsparse_status_invalid_size – if
rows
orcols
orell_width
is invalid.rocsparse_status_invalid_value – if
idx_type
oridx_base
ordata_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
orell_cols
orell_col_ind
orell_val
is invalid.rocsparse_status_invalid_size – if
rows
orcols
orell_block_dim
is invalid.rocsparse_status_invalid_value – if
ell_block_dir
oridx_type
oridx_base
ordata_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
orcoo_row_ind
orcoo_col_ind
orcoo_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
orcoo_ind
orcoo_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
orcoo_ind
orcoo_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
orcsc_col_ptr
orcsc_row_ind
orcsc_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
orell_col_ind
orell_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
orbsr_row_ptr
orbsr_col_ind
orbsr_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
orcols
ornnz
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
orvalues
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
orvalues
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
orbatch_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
oroffsets_batch_stride
orcolumns_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
oroffsets_batch_stride
orrows_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
ordata
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
ordata
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
orvalues
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
orvalues
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
orvalues
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
orvalues
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
iforder=rocsparse_order_column
orld*cols
iforder=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
orvalues
is invalid.rocsparse_status_invalid_size – if
rows
orcols
orld
is invalid.rocsparse_status_invalid_value – if
data_type
ororder
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
iforder=rocsparse_order_column
orld*cols
iforder=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
orvalues
is invalid.rocsparse_status_invalid_size – if
rows
orcols
orld
is invalid.rocsparse_status_invalid_value – if
data_type
ororder
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
iforder=rocsparse_order_column
orld*cols
iforder=rocsparse_order_row
).
- Return values:
rocsparse_status_success – the operation completed successfully.
rocsparse_status_invalid_pointer – if
descr
orvalues
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
iforder=rocsparse_order_column
orld*cols
iforder=rocsparse_order_row
).
- Return values:
rocsparse_status_success – the operation completed successfully.
rocsparse_status_invalid_pointer –
descr
orvalues
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
orbatch_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
orbatch_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
ory
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
orresult
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
orresult
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 inx_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
orx_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