3.2.1.Dense Vector Format

Dense vectors are represented with a single data array that is stored linearly in memory, such as the following\(7 \times 1\) dense vector.

3.2.2.Sparse Vector Format

Sparse vectors are represented with two arrays.

• Thevalues array stores the nonzero values from the equivalent array in dense format.

• Theindices array represent the positions of the corresponding nonzero values in the equivalent array in dense format.

For example, the dense vector in section 3.2.1 can be stored as a sparse vector with zero-based or one-based indexing.

3.3.1.Dense Matrix Format

A dense matrix can be stored in bothrow-major andcolumn-major memory layout (ordering) and it is represented by the following parameters.

• Thenumber of rows in the matrix.

• Thenumber of columns in the matrix.

• Theleading dimension, which must be

  • Greater than or equal to thenumber of columns in therow-major layout

  • Greater than or equal to thenumber of rows in thecolumn-major layout

• The pointers to thevalues array of length

  • \(rows \times leading\; dimension\) in therow-major layout

  • \(columns \times leading\; dimension\) in thecolumn-major layout

The following figure represents a\(5 \times 2\) dense matrix with both memory layouts

The indices within the matrix represents the contiguous locations in memory.

The leading dimension is useful to represent a sub-matrix within the original one

3.3.2.Coordinate (COO)

A sparse matrix stored inCOO format is represented by the following parameters.

• Thenumber of rows in the matrix.

• Thenumber of columns in the matrix.

• Thenumber of non-zero elements (nnz) in the matrix.

• The pointers to therow indices array of lengthnnz that contains the row indices of the corresponding elements in thevalues array.

• The pointers to thecolumn indices array of lengthnnz that contains the column indices of the corresponding elements in thevalues array.

• The pointers to thevalues array of lengthnnz that holds all nonzero values of the matrix in row-major ordering.

• Each entry of the COO representation consists of a<row,column> pair.

• The COO format is assumed to be sortedby row.

The following example shows a\(5 \times 4\) matrix represented in COO format.

Given an entry in the COO format (zero-base), the corresponding position in the dense matrix is computed as:

// row-majorrows_indices[i]*leading_dimension+column_indices[i]// column-majorcolumn_indices[i]*leading_dimension+rows_indices[i]

3.3.3.Compressed Sparse Row (CSR)

TheCSR format is similar to COO, where therow indices are compressed and replaced by an array ofoffsets.

A sparse matrix stored in CSR format is represented by the following parameters.

• Thenumber of rows in the matrix.

• Thenumber of columns in the matrix.

• Thenumber of non-zero elements (nnz) in the matrix.

• The pointers to therow offsets array of lengthnumber of rows + 1 that represents the starting position of each row in thecolumns and values arrays.

• The pointers to thecolumn indices array of lengthnnz that contains the column indices of the corresponding elements in thevalues array.

• The pointers to thevalues array of lengthnnz that holds all nonzero values of the matrix in row-major ordering.

The following example shows a\(5 \times 4\) matrix represented in CSR format.

Given an entry in the CSR format (zero-base), the corresponding position in the dense matrix is computed as:

// row-majorrow*leading_dimension+column_indices[row_offsets[row]+k]// column-majorcolumn_indices[row_offsets[row]+k]*leading_dimension+row

3.3.4.Compressed Sparse Column (CSC)

TheCSC format is similar to COO, where thecolumn indices are compressed and replaced by an array ofoffsets.

A sparse matrix stored in CSC format is represented by the following parameters.

• Thenumber of rows in the matrix.

• Thenumber of columns in the matrix.

• Thenumber of non-zero elements (nnz) in the matrix.

• The pointers to thecolumn offsets array of lengthnumber of column + 1 that represents the starting position of each column in thecolumns and values arrays.

• The pointers to therow indices array of lengthnnz that contains row indices of the corresponding elements in thevalues array.

• The pointers to thevalues array of lengthnnz that holds all nonzero values of the matrix in column-major ordering.

The following example shows a\(5 \times 4\) matrix represented in CSC format.

Given an entry in the CSC format (zero-base), the corresponding position in the dense matrix is computed as:

// row-majorrow_indices[column_offsets[column]+k]*leading_dimension+column// column-majorcolumn*leading_dimension+row_indices[column_offsets[column]+k]

3.3.5.Sliced Ellpack (SELL)

TheSliced Ellpack format is standardized and well-known as the state of the art.This format allows to significantly improve the performance of all problems that involve low variability in the number of nonzero elements per row.

A matrix in the Sliced Ellpack format is divided intoslices of anexact number of rows (\(sliceSize\)), defined by the user.The maximum row length (i.e., the maximum non-zeros per row) is found for each slice, and every row in the slice is padded to the maximum row length.The value-1 is used for padding.

A\(m \times n\) sparse matrix\(A\) is equivalent to asliced sparse matrix\(A_{s}\) with\(nslices = \left \lceil{\frac{m}{sliceSize}}\right \rceil\) slice rows and\(n\) columns.To improve memory coalescing and memory utilization, each slice is stored incolumn-major order.

A sparse matrix stored in SELL format is represented by the following parameters.

• Thenumber of slices.

• Thenumber of rows in the matrix.

• Thenumber of columns in the matrix.

• Thenumber of non-zero elements (nnz) in the matrix.

• Thetotal number elements (sellValuesSize), including non-zero values and padded elements.

• The pointer to theslice offsets of length\(nslices + 1\) that holds offsets of the slides corresponding to the columns and values arrays.

• The pointer to thecolumn indices array of lengthsellValuesSize that contains column indices of the corresponding elements in thevalues array. The column indices are stored incolumn-major layout. Value-1 refers to padding.

• The pointer to thevalues array of lengthsellValuesSize that holds all non-zero values and padding incolumn-major layout.

The following example shows a\(5 \times 4\) matrix represented in SELL format.

3.3.6.Block Sparse Row (BSR)

The BSR format is similar to CSR, where thecolumn indices represent two-dimensional blocks instead of a single matrix entry.

A matrix in the Block Sparse Row format is organized into blocks of size\(blockSize\), defined by the user.

A\(m \times n\) sparse matrix\(A\) is equivalent to ablock sparse matrix\(A_{B}\):\(mb \times nb\) with\(mb = \frac{m}{blockSize}\)block rows and\(nb = \frac{n}{blockSize}\)block columns.If\(m\) or\(n\) is not multiple of\(blockSize\), the user needs to pad the matrix with zeros.

The BSR format stores the blocks in row-major ordering. However, the internal storage format of blocks can becolumn-major (cusparseDirection_t=CUSPARSE_DIRECTION_COLUMN) orrow-major (cusparseDirection_t=CUSPARSE_DIRECTION_ROW), independently of the base index.

A sparse matrix stored in BSR format is represented by the following parameters.

• Theblock size.

• Thenumber of row blocks in the matrix.

• Thenumber of column blocks in the matrix.

• Thenumber of non-zero blocks (nnzb) in the matrix.

• The pointers to therow block offsets array of lengthnumber of row blocks + 1 that represents the starting position of each row block in thecolumns and values arrays.

• The pointers to thecolumn block indices array of lengthnnzb that contains the location of the corresponding elements in the values array.

• The pointers to thevalues array of lengthnnzb that holds all nonzero values of the matrix.

The following example shows a\(4 \times 7\) matrix represented in BSR format.

3.3.7.Blocked Ellpack (BLOCKED-ELL)

The Blocked Ellpack format is similar to the standard Ellpack, where thecolumn indices represent two-dimensional blocks instead of a single matrix entry.

A matrix in the Blocked Ellpack format is organized into blocks of size\(blockSize\), defined by the user. The number of columns per row\(nEllCols\) is also defined by the user (\(nEllCols \le n\)).

A\(m \times n\) sparse matrix\(A\) is equivalent to aBlocked-ELL matrix\(A_{B}\):\(mb \times nb\) with\(mb = \left \lceil{\frac{m}{blockSize}}\right \rceil\)block rows, and\(nb = \left \lceil{\frac{nEllCols}{blockSize}}\right \rceil\) block columns.If\(m\) or\(n\) is not multiple of\(blockSize\), then the remaining elements are zero.

A sparse matrix stored in Blocked-ELL format is represented by the following parameters.

• Theblock size.

• Thenumber of rows in the matrix.

• Thenumber of columns in the matrix.

• Thenumber of columns per row (nEllCols) in the matrix.

• The pointers to thecolumn block indices array of length\(mb \times nb\) that contains the location of the corresponding elements in the values array. Empty blocks can be represented with-1 index.

• The pointers to thevalues array of length\(m \times nEllCols\) that holds all nonzero values of the matrix in row-major ordering.

The following example shows a\(9 \times 9\) matrix represented in Blocked-ELL format.

3.3.8.Extended BSR Format (BSRX) [DEPRECATED]

BSRX is the same as the BSR format, but the arraybsrRowPtrA is separated into two parts. The first nonzero block of each row is still specified by the arraybsrRowPtrA, which is the same as in BSR, but the position next to the last nonzero block of each row is specified by the arraybsrEndPtrA. Briefly, BSRX format is simply like a 4-vector variant of BSR format.

MatrixA is represented in BSRX format by the following parameters.

A simple conversion between BSR and BSRX can be done as follows. Suppose the developer has a\(2 \times 3\) block sparse matrix\(A_{b}\) represented as shown.

Assume it has this BSR format:

ThebsrRowPtrA of the BSRX format is simply the first two elements of thebsrRowPtrA BSR format. ThebsrEndPtrA of BSRX format is the last two elements of thebsrRowPtrA of BSR format.

The advantage of the BSRX format is that the developer can specify a submatrix in the original BSR format by modifyingbsrRowPtrA andbsrEndPtrA while keepingbsrColIndA andbsrValA unchanged.

For example, to create another block matrix\(\widetilde{A} = \begin{bmatrix}O & O & O \\O & A_{11} & O \\\end{bmatrix}\) that is slightly different from\(A\) , the developer can keepbsrColIndA andbsrValA, but reconstruct\(\widetilde{A}\) by properly setting ofbsrRowPtrA andbsrEndPtrA. The following 4-vector characterizes\(\widetilde{A}\) .

4.1.1.cudaDataType_t

The section describes the types shared by multiple CUDA Libraries and defined in the header filelibrary_types.h. ThecudaDataType type is an enumerator to specify the data precision. It is used when the data reference does not carry the type itself (e.g.void*). For example, it is used in the routinecusparseSpMM().

IMPORTANT: The Generic API routines allow all data types reported in the respective section of the documentation only on GPU architectures withnative support for them. If a specific GPU model does not providenative support for a given data type, the routine returnsCUSPARSE_STATUS_ARCH_MISMATCH error.

Unsupported data types and Compute Capability (CC):

• __half on GPUs withCC<53 (e.g. Kepler)

• __nv_bfloat16 on GPUs withCC<80 (e.g. Kepler, Maxwell, Pascal, Volta, Turing)

seehttps://developer.nvidia.com/cuda-gpus

4.1.2.cusparseStatus_t

This data type represents the status returned by the library functions and it can have the following values:

4.1.3.cusparseHandle_t

This is a pointer type to an opaque cuSPARSE context, which the user must initialize by calling prior to callingcusparseCreate() any other library function. The handle created and returned bycusparseCreate() must be passed to every cuSPARSE function.

4.1.4.cusparsePointerMode_t

This type indicates whether the scalar values are passed by reference on the host or device. It is important to point out that if several scalar values are passed by reference in the function call, all of them will conform to the same single pointer mode. The pointer mode can be set and retrieved usingcusparseSetPointerMode() andcusparseGetPointerMode() routines, respectively.

4.1.5.cusparseOperation_t

This type indicates which operations is applied to the related input (e.g. sparse matrix, or vector).

4.1.6.cusparseDiagType_t

This type indicates if the matrix diagonal entries are unity. The diagonal elements are always assumed to be present, but ifCUSPARSE_DIAG_TYPE_UNIT is passed to an API routine, then the routine assumes that all diagonal entries are unity and will not read or modify those entries. Note that in this case the routine assumes the diagonal entries are equal to one, regardless of what those entries are actually set to in memory.

4.1.7.cusparseFillMode_t

This type indicates if the lower or upper part of a matrix is stored in sparse storage.

4.1.8.cusparseIndexBase_t

This type indicates if the base of the matrix indices is zero or one.

4.1.9.cusparseDirection_t

This type indicates whether the elements of a dense matrix should be parsed by rows or by columns (assuming column-major storage in memory of the dense matrix) in function cusparse[S|D|C|Z]nnz. Besides storage format of blocks in BSR format is also controlled by this type.

4.2.1.cusparseCreate()

cusparseStatus_tcusparseCreate(cusparseHandle_t*handle)

This function initializes the cuSPARSE library and creates a handle on the cuSPARSE context. It must be called before any other cuSPARSE API function is invoked. It allocates hardware resources necessary for accessing the GPU.

Refer tocusparseStatus_t for the description of the return status.

4.2.2.cusparseDestroy()

cusparseStatus_tcusparseDestroy(cusparseHandle_thandle)

This function releases CPU-side resources used by the cuSPARSE library. The release of GPU-side resources may be deferred until the application shuts down.

Refer tocusparseStatus_t for the description of the return status.

4.2.3.cusparseGetErrorName()

constchar*cusparseGetErrorString(cusparseStatus_tstatus)

The function returns the string representation of an error code enum name. If the error code is not recognized, “unrecognized error code” is returned.

4.2.4.cusparseGetErrorString()

constchar*cusparseGetErrorString(cusparseStatus_tstatus)

Returns the description string for an error code. If the error code is not recognized, “unrecognized error code” is returned.

4.2.5.cusparseGetProperty()

cusparseStatus_tcusparseGetProperty(libraryPropertyTypetype,int*value)

The function returns the value of the requested property. Refer tolibraryPropertyType for supported types.

libraryPropertyType (defined inlibrary_types.h):

Refer tocusparseStatus_t for the description of the return status.

4.2.6.cusparseGetVersion()

cusparseStatus_tcusparseGetVersion(cusparseHandle_thandle,int*version)

This function returns the version number of the cuSPARSE library.

Refer tocusparseStatus_t for the description of the return status.

4.2.7.cusparseGetPointerMode()

cusparseStatus_tcusparseGetPointerMode(cusparseHandlethandle,cusparsePointerMode_t*mode)

This function obtains the pointer mode used by the cuSPARSE library. Please see the section on thecusparsePointerMode_t type for more details.

Refer tocusparseStatus_t for the description of the return status.

4.2.8.cusparseSetPointerMode()

cusparseStatus_tcusparseSetPointerMode(cusparseHandle_thandle,cusparsePointerMode_tmode)

This function sets the pointer mode used by the cuSPARSE library. Thedefault is for the values to be passed by reference on the host. Please see the section on thecublasPointerMode_t type for more details.

Refer tocusparseStatus_t for the description of the return status.

4.2.9.cusparseGetStream()

cusparseStatus_tcusparseGetStream(cusparseHandle_thandle,cudaStream_t*streamId)

This function gets the cuSPARSE library stream, which is being used to to execute all calls to the cuSPARSE library functions. If the cuSPARSE library stream is not set, all kernels use the default NULL stream.

Refer tocusparseStatus_t for the description of the return status.

4.2.10.cusparseSetStream()

cusparseStatus_tcusparseSetStream(cusparseHandle_thandle,cudaStream_tstreamId)

This function sets the stream to be used by the cuSPARSE library to execute its routines.

Refer tocusparseStatus_t for the description of the return status.

4.3.1.cusparseLoggerSetCallback()

cusparseStatus_tcusparseLoggerSetCallback(cusparseLoggerCallback_tcallback)

Experimental: The function sets the logging callback function.

wherecusparseLoggerCallback_t has the following signature:

void(*cusparseLoggerCallback_t)(intlogLevel,constchar*functionName,constchar*message)

SeecusparseStatus_t for the description of the return status.

4.3.2.cusparseLoggerSetFile()

cusparseStatus_tcusparseLoggerSetFile(FILE*file)

Experimental: The function sets the logging output file. Note: once registered using this function call, the provided file handle must not be closed unless the function is called again to switch to a different file handle.

SeecusparseStatus_t for the description of the return status.

4.3.3.cusparseLoggerOpenFile()

cusparseStatus_tcusparseLoggerOpenFile(constchar*logFile)

Experimental: The function opens a logging output file in the given path.

SeecusparseStatus_t for the description of the return status.

4.3.4.cusparseLoggerSetLevel()

cusparseStatus_tcusparseLoggerSetLevel(intlevel)

Experimental: The function sets the value of the logging level. path.

SeecusparseStatus_t for the description of the return status

4.3.5.cusparseLoggerSetMask()

cusparseStatus_tcusparseLoggerSetMask(intmask)

Experimental: The function sets the value of the logging mask.

SeecusparseStatus_t for the description of the return status

5.2.1.cusparseAction_t

This type indicates whether the operation is performed only on indices or on data and indices.

5.2.2.cusparseMatDescr_t

This structure is used to describe the shape and properties of a matrix.

typedefstruct{cusparseMatrixType_tMatrixType;cusparseFillMode_tFillMode;cusparseDiagType_tDiagType;cusparseIndexBase_tIndexBase;}cusparseMatDescr_t;

5.2.3.cusparseMatrixType_t

This type indicates the type of matrix stored in sparse storage. Notice that for symmetric, Hermitian and triangular matrices only their lower or upper part is assumed to be stored.

The whole idea of matrix type and fill mode is to keep minimum storage for symmetric/Hermitian matrix, and also to take advantage of symmetric property on SpMV (Sparse Matrix Vector multiplication). To computey=A*x whenA is symmetric and only lower triangular part is stored, two steps are needed. First step is to computey=(L+D)*x and second step is to computey=L^T*x+y. Given the fact that the transpose operationy=L^T*x is 10x slower than non-transpose versiony=L*x, the symmetric property does not show up any performance gain. It is better for the user to extend the symmetric matrix to a general matrix and applyy=A*x with matrix typeCUSPARSE_MATRIX_TYPE_GENERAL.

In general, SpMV, preconditioners (incomplete Cholesky or incomplete LU) and triangular solver are combined together in iterative solvers, for example PCG and GMRES. If the user always uses general matrix (instead of symmetric matrix), there is no need to support other than general matrix in preconditioners. Therefore the new routines,[bsr|csr]sv2 (triangular solver),[bsr|csr]ilu02 (incomplete LU) and[bsr|csr]ic02 (incomplete Cholesky), only support matrix typeCUSPARSE_MATRIX_TYPE_GENERAL.

5.2.4.cusparseColorInfo_t [DEPRECATED]

This is a pointer type to an opaque structure holding the information used incsrcolor().

5.2.5.cusparseSolvePolicy_t [DEPRECATED]

This type indicates whether level information is generated and used incsrsv2,csric02,csrilu02,bsrsv2,bsric02andbsrilu02.

5.2.6.bsric02Info_t [DEPRECATED]

This is a pointer type to an opaque structure holding the information used inbsric02_bufferSize(),bsric02_analysis(), andbsric02().

5.2.7.bsrilu02Info_t [DEPRECATED]

This is a pointer type to an opaque structure holding the information used inbsrilu02_bufferSize(),bsrilu02_analysis(), andbsrilu02().

5.2.8.bsrsm2Info_t [DEPRECATED]

This is a pointer type to an opaque structure holding the information used inbsrsm2_bufferSize(),bsrsm2_analysis(), andbsrsm2_solve().

5.2.9.bsrsv2Info_t [DEPRECATED]

This is a pointer type to an opaque structure holding the information used inbsrsv2_bufferSize(),bsrsv2_analysis(), andbsrsv2_solve().

5.2.10.csric02Info_t [DEPRECATED]

This is a pointer type to an opaque structure holding the information used incsric02_bufferSize(),csric02_analysis(), andcsric02().

5.2.11.csrilu02Info_t [DEPRECATED]

This is a pointer type to an opaque structure holding the information used incsrilu02_bufferSize(),csrilu02_analysis(), andcsrilu02().

5.3.1.cusparseCreateColorInfo() [DEPRECATED]

>The routine will be removed in the next major release

cusparseStatus_tcusparseCreateColorInfo(cusparseColorInfo_t*info)

This function creates and initializes thecusparseColorInfo_t structure todefault values.

Input

SeecusparseStatus_t for the description of the return status.

5.3.2.cusparseCreateMatDescr()

cusparseStatus_tcusparseCreateMatDescr(cusparseMatDescr_t*descrA)

This function initializes the matrix descriptor. It sets the fieldsMatrixType andIndexBase to thedefault valuesCUSPARSE_MATRIX_TYPE_GENERAL andCUSPARSE_INDEX_BASE_ZERO , respectively, while leaving other fields uninitialized.

Input

SeecusparseStatus_t for the description of the return status.

5.3.3.cusparseDestroyColorInfo() [DEPRECATED]

>The routine will be removed in the next major release

cusparseStatus_tcusparseDestroyColorInfo(cusparseColorInfo_tinfo)

This function destroys and releases any memory required by the structure.

Input

SeecusparseStatus_t for the description of the return status.

5.3.4.cusparseDestroyMatDescr()

cusparseStatus_tcusparseDestroyMatDescr(cusparseMatDescr_tdescrA)

This function releases the memory allocated for the matrix descriptor.

Input

SeecusparseStatus_t for the description of the return status.

5.3.5.cusparseGetMatDiagType()

cusparseDiagType_tcusparseGetMatDiagType(constcusparseMatDescr_tdescrA)

This function returns theDiagType field of the matrix descriptordescrA.

Input

Returned

5.3.6.cusparseGetMatFillMode()

cusparseFillMode_tcusparseGetMatFillMode(constcusparseMatDescr_tdescrA)

This function returns theFillMode field of the matrix descriptordescrA.

Input

Returned

5.3.7.cusparseGetMatIndexBase()

cusparseIndexBase_tcusparseGetMatIndexBase(constcusparseMatDescr_tdescrA)

This function returns theIndexBase field of the matrix descriptordescrA.

Input

Returned

5.3.8.cusparseGetMatType()

cusparseMatrixType_tcusparseGetMatType(constcusparseMatDescr_tdescrA)

This function returns theMatrixType field of the matrix descriptordescrA.

Input

Returned

5.3.9.cusparseSetMatDiagType()

cusparseStatus_tcusparseSetMatDiagType(cusparseMatDescr_tdescrA,cusparseDiagType_tdiagType)

This function sets theDiagType field of the matrix descriptordescrA.

Input

Output

SeecusparseStatus_t for the description of the return status.

5.3.10.cusparseSetMatFillMode()

cusparseStatus_tcusparseSetMatFillMode(cusparseMatDescr_tdescrA,cusparseFillMode_tfillMode)

This function sets theFillMode field of the matrix descriptordescrA.

Input

Output

SeecusparseStatus_t for the description of the return status.

5.3.11.cusparseSetMatIndexBase()

cusparseStatus_tcusparseSetMatIndexBase(cusparseMatDescr_tdescrA,cusparseIndexBase_tbase)

This function sets theIndexBase field of the matrix descriptordescrA.

Input

Output

SeecusparseStatus_t for the description of the return status.

5.3.12.cusparseSetMatType()

cusparseStatus_tcusparseSetMatType(cusparseMatDescr_tdescrA,cusparseMatrixType_ttype)

This function sets theMatrixType field of the matrix descriptordescrA.

Input

Output

SeecusparseStatus_t for the description of the return status.

5.3.13.cusparseCreateCsric02Info() [DEPRECATED]

>The routine will be removed in the next major release

cusparseStatus_tcusparseCreateCsric02Info(csric02Info_t*info);

This function creates and initializes the solve and analysis structure of incomplete Cholesky todefault values.

Input

SeecusparseStatus_t for the description of the return status.

5.3.14.cusparseDestroyCsric02Info() [DEPRECATED]

>The routine will be removed in the next major release

cusparseStatus_tcusparseDestroyCsric02Info(csric02Info_tinfo);

This function destroys and releases any memory required by the structure.

Input

SeecusparseStatus_t for the description of the return status.

5.3.15.cusparseCreateCsrilu02Info() [DEPRECATED]

>The routine will be removed in the next major release

cusparseStatus_tcusparseCreateCsrilu02Info(csrilu02Info_t*info);

This function creates and initializes the solve and analysis structure of incomplete LU todefault values.

Input

SeecusparseStatus_t for the description of the return status.

5.3.16.cusparseDestroyCsrilu02Info() [DEPRECATED]

>The routine will be removed in the next major release

cusparseStatus_tcusparseDestroyCsrilu02Info(csrilu02Info_tinfo);

This function destroys and releases any memory required by the structure.

Input

SeecusparseStatus_t for the description of the return status.

5.3.17.cusparseCreateBsrsv2Info() [DEPRECATED]

>The routine will be removed in the next major release

cusparseStatus_tcusparseCreateBsrsv2Info(bsrsv2Info_t*info);

This function creates and initializes the solve and analysis structure of bsrsv2 todefault values.

Input

SeecusparseStatus_t for the description of the return status.

5.3.18.cusparseDestroyBsrsv2Info() [DEPRECATED]

>The routine will be removed in the next major release

cusparseStatus_tcusparseDestroyBsrsv2Info(bsrsv2Info_tinfo);

This function destroys and releases any memory required by the structure.

Input

SeecusparseStatus_t for the description of the return status.

5.3.19.cusparseCreateBsrsm2Info() [DEPRECATED]

>The routine will be removed in the next major release

cusparseStatus_tcusparseCreateBsrsm2Info(bsrsm2Info_t*info);

This function creates and initializes the solve and analysis structure of bsrsm2 todefault values.

Input

SeecusparseStatus_t for the description of the return status.

5.3.20.cusparseDestroyBsrsm2Info() [DEPRECATED]

>The routine will be removed in the next major release

cusparseStatus_tcusparseDestroyBsrsm2Info(bsrsm2Info_tinfo);

This function destroys and releases any memory required by the structure.

Input

SeecusparseStatus_t for the description of the return status.

5.3.21.cusparseCreateBsric02Info() [DEPRECATED]

>The routine will be removed in the next major release

cusparseStatus_tcusparseCreateBsric02Info(bsric02Info_t*info);

This function creates and initializes the solve and analysis structure of block incomplete Cholesky todefault values.

Input

SeecusparseStatus_t for the description of the return status.

5.3.22.cusparseDestroyBsric02Info() [DEPRECATED]

>The routine will be removed in the next major release

cusparseStatus_tcusparseDestroyBsric02Info(bsric02Info_tinfo);

This function destroys and releases any memory required by the structure.

Input

SeecusparseStatus_t for the description of the return status.

5.3.23.cusparseCreateBsrilu02Info() [DEPRECATED]

>The routine will be removed in the next major release

cusparseStatus_tcusparseCreateBsrilu02Info(bsrilu02Info_t*info);

This function creates and initializes the solve and analysis structure of block incomplete LU todefault values.

Input

SeecusparseStatus_t for the description of the return status.

5.3.24.cusparseDestroyBsrilu02Info() [DEPRECATED]

>The routine will be removed in the next major release

cusparseStatus_tcusparseDestroyBsrilu02Info(bsrilu02Info_tinfo);

This function destroys and releases any memory required by the structure.

Input

SeecusparseStatus_t for the description of the return status.

5.3.25.cusparseCreatePruneInfo() [DEPRECATED]

>The routine will be removed in the next major release

cusparseStatus_tcusparseCreatePruneInfo(pruneInfo_t*info);

This function creates and initializes structure ofprune todefault values.

Input

SeecusparseStatus_t for the description of the return status.

5.3.26.cusparseDestroyPruneInfo() [DEPRECATED]

>The routine will be removed in the next major release

cusparseStatus_tcusparseDestroyPruneInfo(pruneInfo_tinfo);

This function destroys and releases any memory required by the structure.

Input

SeecusparseStatus_t for the description of the return status.

5.4.1.cusparse<t>bsrmv() [DEPRECATED]

cusparseStatus_tcusparseSbsrmv(cusparseHandle_thandle,cusparseDirection_tdir,cusparseOperation_ttrans,intmb,intnb,intnnzb,constfloat*alpha,constcusparseMatDescr_tdescr,constfloat*bsrVal,constint*bsrRowPtr,constint*bsrColInd,intblockDim,constfloat*x,constfloat*beta,float*y)cusparseStatus_tcusparseDbsrmv(cusparseHandle_thandle,cusparseDirection_tdir,cusparseOperation_ttrans,intmb,intnb,intnnzb,constdouble*alpha,constcusparseMatDescr_tdescr,constdouble*bsrVal,constint*bsrRowPtr,constint*bsrColInd,intblockDim,constdouble*x,constdouble*beta,double*y)cusparseStatus_tcusparseCbsrmv(cusparseHandle_thandle,cusparseDirection_tdir,cusparseOperation_ttrans,intmb,intnb,intnnzb,constcuComplex*alpha,constcusparseMatDescr_tdescr,constcuComplex*bsrVal,constint*bsrRowPtr,constint*bsrColInd,intblockDim,constcuComplex*x,constcuComplex*beta,cuComplex*y)cusparseStatus_tcusparseZbsrmv(cusparseHandle_thandle,cusparseDirection_tdir,cusparseOperation_ttrans,intmb,intnb,intnnzb,constcuDoubleComplex*alpha,constcusparseMatDescr_tdescr,constcuDoubleComplex*bsrVal,constint*bsrRowPtr,constint*bsrColInd,intblockDim,constcuDoubleComplex*x,constcuDoubleComplex*beta,cuDoubleComplex*y)

This function performs the matrix-vector operation

where\(A\text{ is an }(mb \ast blockDim) \times (nb \ast blockDim)\) sparse matrix that is defined in BSR storage format by the three arraysbsrVal,bsrRowPtr, andbsrColInd);x andy are vectors;\(\alpha\text{ and }\beta\) are scalars; and

bsrmv() has the following properties:

• The routine requires no extra storage.

• The routine supports asynchronous execution.

• The routine supports CUDA graph capture.

Several comments onbsrmv():

• OnlyblockDim>1 is supported

• OnlyCUSPARSE_OPERATION_NON_TRANSPOSE is supported, that is

• OnlyCUSPARSE_MATRIX_TYPE_GENERAL is supported.

• The size of vectorx should be\((nb \ast blockDim)\) at least, and the size of vectory should be\((mb \ast blockDim)\) at least; otherwise, the kernel may returnCUSPARSE_STATUS_EXECUTION_FAILED because of an out-of-bounds array.

For example, suppose the user has a CSR format and wants to trybsrmv(), the following code demonstrates how to usecsr2bsr() conversion andbsrmv() multiplication in single precision.

// Suppose that A is m x n sparse matrix represented by CSR format,// hx is a host vector of size n, and hy is also a host vector of size m.// m and n are not multiple of blockDim.// step 1: transform CSR to BSR with column-major orderintbase,nnz;intnnzb;cusparseDirection_tdirA=CUSPARSE_DIRECTION_COLUMN;intmb=(m+blockDim-1)/blockDim;intnb=(n+blockDim-1)/blockDim;cudaMalloc((void**)&bsrRowPtrC,sizeof(int)*(mb+1));cusparseXcsr2bsrNnz(handle,dirA,m,n,descrA,csrRowPtrA,csrColIndA,blockDim,descrC,bsrRowPtrC,&nnzb);cudaMalloc((void**)&bsrColIndC,sizeof(int)*nnzb);cudaMalloc((void**)&bsrValC,sizeof(float)*(blockDim*blockDim)*nnzb);cusparseScsr2bsr(handle,dirA,m,n,descrA,csrValA,csrRowPtrA,csrColIndA,blockDim,descrC,bsrValC,bsrRowPtrC,bsrColIndC);// step 2: allocate vector x and vector y large enough for bsrmvcudaMalloc((void**)&x,sizeof(float)*(nb*blockDim));cudaMalloc((void**)&y,sizeof(float)*(mb*blockDim));cudaMemcpy(x,hx,sizeof(float)*n,cudaMemcpyHostToDevice);cudaMemcpy(y,hy,sizeof(float)*m,cudaMemcpyHostToDevice);// step 3: perform bsrmvcusparseSbsrmv(handle,dirA,transA,mb,nb,nnzb,&alpha,descrC,bsrValC,bsrRowPtrC,bsrColIndC,blockDim,x,&beta,y);

Input

Output

SeecusparseStatus_t for the description of the return status.

5.4.2.cusparse<t>bsrxmv() [DEPRECATED]

>The routine will be removed in the next major release

cusparseStatus_tcusparseSbsrxmv(cusparseHandle_thandle,cusparseDirection_tdir,cusparseOperation_ttrans,intsizeOfMask,intmb,intnb,intnnzb,constfloat*alpha,constcusparseMatDescr_tdescr,constfloat*bsrVal,constint*bsrMaskPtr,constint*bsrRowPtr,constint*bsrEndPtr,constint*bsrColInd,intblockDim,constfloat*x,constfloat*beta,float*y)cusparseStatus_tcusparseDbsrxmv(cusparseHandle_thandle,cusparseDirection_tdir,cusparseOperation_ttrans,intsizeOfMask,intmb,intnb,intnnzb,constdouble*alpha,constcusparseMatDescr_tdescr,constdouble*bsrVal,constint*bsrMaskPtr,constint*bsrRowPtr,constint*bsrEndPtr,constint*bsrColInd,intblockDim,constdouble*x,constdouble*beta,double*y)cusparseStatus_tcusparseCbsrxmv(cusparseHandle_thandle,cusparseDirection_tdir,cusparseOperation_ttrans,intsizeOfMask,intmb,intnb,intnnzb,constcuComplex*alpha,constcusparseMatDescr_tdescr,constcuComplex*bsrVal,constint*bsrMaskPtr,constint*bsrRowPtr,constint*bsrEndPtr,constint*bsrColInd,intblockDim,constcuComplex*x,constcuComplex*beta,cuComplex*y)cusparseStatus_tcusparseZbsrxmv(cusparseHandle_thandle,cusparseDirection_tdir,cusparseOperation_ttrans,intsizeOfMask,intmb,intnb,intnnzb,constcuDoubleComplex*alpha,constcusparseMatDescr_tdescr,constcuDoubleComplex*bsrVal,constint*bsrMaskPtr,constint*bsrRowPtr,constint*bsrEndPtr,constint*bsrColInd,intblockDim,constcuDoubleComplex*x,constcuDoubleComplex*beta,cuDoubleComplex*y)

This function performs absrmv and a mask operation

where\(A\text{ is an }(mb \ast blockDim) \times (nb \ast blockDim)\) sparse matrix that is defined in BSRX storage format by the four arraysbsrVal,bsrRowPtr,bsrEndPtr, andbsrColInd);x andy are vectors;\(\alpha\text{~and~}\beta\) are scalars; and

The mask operation is defined by arraybsrMaskPtr which contains updated block row indices of\(y\) . If row\(i\) is not specified inbsrMaskPtr, thenbsrxmv() does not touch row block\(i\) of\(A\) and\(y\) .

For example, consider the\(2 \times 3\) block matrix\(A\):

and its one-based BSR format (three vector form) is:

Suppose we want to do the followingbsrmv operation on a matrix\(\bar{A}\) which is slightly different from\(A\) .

We don’t need to create another BSR format for the new matrix\(\bar{A}\) , all that we should do is to keepbsrVal andbsrColInd unchanged, but modifybsrRowPtr and add an additional arraybsrEndPtr which points to the last nonzero elements per row of\(\bar{A}\) plus 1.

For example, the followingbsrRowPtr andbsrEndPtr can represent matrix\(\bar{A}\):

Further we can use a mask operator (specified by arraybsrMaskPtr) to update particular block row indices of\(y\) only because\(y_{1}\) is never changed. In this case,bsrMaskPtr\(=\) [2] andsizeOfMask=1.

The mask operator is equivalent to the following operation:

If a block row is not present in thebsrMaskPtr, then no calculation is performed on that row, and the corresponding value iny is unmodified. The question mark “?” is used to inidcate row blocks not inbsrMaskPtr.

In this case, first row block is not present inbsrMaskPtr, sobsrRowPtr[0] andbsrEndPtr[0] are not touched also.

bsrxmv() has the following properties:

• The routine requires no extra storage.

• The routine supports asynchronous execution.

• The routine supports CUDA graph capture.

A couple of comments onbsrxmv():

• OnlyblockDim>1 is supported

• OnlyCUSPARSE_OPERATION_NON_TRANSPOSE andCUSPARSE_MATRIX_TYPE_GENERAL are supported.

• ParametersbsrMaskPtr,bsrRowPtr,bsrEndPtr andbsrColInd are consistent with base index, either one-based or zero-based. The above example is one-based.

Input

SeecusparseStatus_t for the description of the return status.

5.4.3.cusparse<t>bsrsv2_bufferSize() [DEPRECATED]

>The routine will be removed in the next major release

cusparseStatus_tcusparseSbsrsv2_bufferSize(cusparseHandle_thandle,cusparseDirection_tdirA,cusparseOperation_ttransA,intmb,intnnzb,constcusparseMatDescr_tdescrA,float*bsrValA,constint*bsrRowPtrA,constint*bsrColIndA,intblockDim,bsrsv2Info_tinfo,int*pBufferSizeInBytes)cusparseStatus_tcusparseDbsrsv2_bufferSize(cusparseHandle_thandle,cusparseDirection_tdirA,cusparseOperation_ttransA,intmb,intnnzb,constcusparseMatDescr_tdescrA,double*bsrValA,constint*bsrRowPtrA,constint*bsrColIndA,intblockDim,bsrsv2Info_tinfo,int*pBufferSizeInBytes)cusparseStatus_tcusparseCbsrsv2_bufferSize(cusparseHandle_thandle,cusparseDirection_tdirA,cusparseOperation_ttransA,intmb,intnnzb,constcusparseMatDescr_tdescrA,cuComplex*bsrValA,constint*bsrRowPtrA,constint*bsrColIndA,intblockDim,bsrsv2Info_tinfo,int*pBufferSizeInBytes)cusparseStatus_tcusparseZbsrsv2_bufferSize(cusparseHandle_thandle,cusparseDirection_tdirA,cusparseOperation_ttransA,intmb,intnnzb,constcusparseMatDescr_tdescrA,cuDoubleComplex*bsrValA,constint*bsrRowPtrA,constint*bsrColIndA,intblockDim,bsrsv2Info_tinfo,int*pBufferSizeInBytes)

This function returns size of the buffer used inbsrsv2, a new sparse triangular linear systemop(A)*y=\(\alpha\)x.

A is an(mb*blockDim)x(mb*blockDim) sparse matrix that is defined in BSR storage format by the three arraysbsrValA,bsrRowPtrA, andbsrColIndA);x andy are the right-hand-side and the solution vectors;\(\alpha\) is a scalar; and

Although there are six combinations in terms of parametertrans and the upper (lower) triangular part ofA,bsrsv2_bufferSize() returns the maximum size buffer among these combinations. The buffer size depends on the dimensionsmb,blockDim, and the number of nonzero blocks of the matrixnnzb. If the user changes the matrix, it is necessary to callbsrsv2_bufferSize() again to have the correct buffer size; otherwise a segmentation fault may occur.

• The routine requires no extra storage.

• The routine supports asynchronous execution.

• The routine supports CUDA graph capture.

Input

Output

SeecusparseStatus_t for the description of the return status.

5.4.4.cusparse<t>bsrsv2_analysis() [DEPRECATED]

>The routine will be removed in the next major release

cusparseStatus_tcusparseSbsrsv2_analysis(cusparseHandle_thandle,cusparseDirection_tdirA,cusparseOperation_ttransA,intmb,intnnzb,constcusparseMatDescr_tdescrA,constfloat*bsrValA,constint*bsrRowPtrA,constint*bsrColIndA,intblockDim,bsrsv2Info_tinfo,cusparseSolvePolicy_tpolicy,void*pBuffer)cusparseStatus_tcusparseDbsrsv2_analysis(cusparseHandle_thandle,cusparseDirection_tdirA,cusparseOperation_ttransA,intmb,intnnzb,constcusparseMatDescr_tdescrA,constdouble*bsrValA,constint*bsrRowPtrA,constint*bsrColIndA,intblockDim,bsrsv2Info_tinfo,cusparseSolvePolicy_tpolicy,void*pBuffer)cusparseStatus_tcusparseDbsrsv2_analysis(cusparseHandle_thandle,cusparseDirection_tdirA,cusparseOperation_ttransA,intmb,intnnzb,constcusparseMatDescr_tdescrA,constcuComplex*bsrValA,constint*bsrRowPtrA,constint*bsrColIndA,intblockDim,bsrsv2Info_tinfo,cusparseSolvePolicy_tpolicy,void*pBuffer)cusparseStatus_tcusparseZbsrsv2_analysis(cusparseHandle_thandle,cusparseDirection_tdirA,cusparseOperation_ttransA,intmb,intnnzb,constcusparseMatDescr_tdescrA,constcuDoubleComplex*bsrValA,constint*bsrRowPtrA,constint*bsrColIndA,intblockDim,bsrsv2Info_tinfo,cusparseSolvePolicy_tpolicy,void*pBuffer)

This function performs the analysis phase ofbsrsv2, a new sparse triangular linear systemop(A)*y=\(\alpha\)x.

A is an(mb*blockDim)x(mb*blockDim) sparse matrix that is defined in BSR storage format by the three arraysbsrValA,bsrRowPtrA, andbsrColIndA);x andy are the right-hand side and the solution vectors;\(\alpha\) is a scalar; and

The block of BSR format is of sizeblockDim*blockDim, stored as column-major or row-major as determined by parameterdirA, which is eitherCUSPARSE_DIRECTION_COLUMN orCUSPARSE_DIRECTION_ROW. The matrix type must beCUSPARSE_MATRIX_TYPE_GENERAL, and the fill mode and diagonal type are ignored.

It is expected that this function will be executed only once for a given matrix and a particular operation type.

This function requires a buffer size returned bybsrsv2_bufferSize(). The address ofpBuffer must be multiple of 128 bytes. If it is not,CUSPARSE_STATUS_INVALID_VALUE is returned.

Functionbsrsv2_analysis() reports a structural zero and computes level information, which stored in the opaque structureinfo. The level information can extract more parallelism for a triangular solver. Howeverbsrsv2_solve() can be done without level information. To disable level information, the user needs to specify the policy of the triangular solver asCUSPARSE_SOLVE_POLICY_NO_LEVEL.

Functionbsrsv2_analysis() always reports the first structural zero, even when parameterpolicy isCUSPARSE_SOLVE_POLICY_NO_LEVEL. No structural zero is reported ifCUSPARSE_DIAG_TYPE_UNIT is specified, even if blockA(j,j) is missing for somej. The user needs to callcusparseXbsrsv2_zeroPivot() to know where the structural zero is.

It is the user’s choice whether to callbsrsv2_solve() ifbsrsv2_analysis() reports a structural zero. In this case, the user can still callbsrsv2_solve(), which will return a numerical zero at the same position as a structural zero. However the resultx is meaningless.

• This function requires temporary extra storage that is allocated internally

• The routine supports asynchronous execution if the Stream Ordered Memory Allocator is available

• The routine supports CUDA graph capture if the Stream Ordered Memory Allocator is available

Input

Output

SeecusparseStatus_t for the description of the return status.

5.4.5.cusparse<t>bsrsv2_solve() [DEPRECATED]

>The routine will be removed in the next major release

cusparseStatus_tcusparseSbsrsv2_solve(cusparseHandle_thandle,cusparseDirection_tdirA,cusparseOperation_ttransA,intmb,intnnzb,constfloat*alpha,constcusparseMatDescr_tdescrA,constfloat*bsrValA,constint*bsrRowPtrA,constint*bsrColIndA,intblockDim,bsrsv2Info_tinfo,constfloat*x,float*y,cusparseSolvePolicy_tpolicy,void*pBuffer)cusparseStatus_tcusparseDbsrsv2_solve(cusparseHandle_thandle,cusparseDirection_tdirA,cusparseOperation_ttransA,intmb,intnnzb,constdouble*alpha,constcusparseMatDescr_tdescrA,constdouble*bsrValA,constint*bsrRowPtrA,constint*bsrColIndA,intblockDim,bsrsv2Info_tinfo,constdouble*x,double*y,cusparseSolvePolicy_tpolicy,void*pBuffer)cusparseStatus_tcusparseCbsrsv2_solve(cusparseHandle_thandle,cusparseDirection_tdirA,cusparseOperation_ttransA,intmb,intnnzb,constcuComplex*alpha,constcusparseMatDescr_tdescrA,constcuComplex*bsrValA,constint*bsrRowPtrA,constint*bsrColIndA,intblockDim,bsrsv2Info_tinfo,constcuComplex*x,cuComplex*y,cusparseSolvePolicy_tpolicy,void*pBuffer)cusparseStatus_tcusparseZbsrsv2_solve(cusparseHandle_thandle,cusparseDirection_tdirA,cusparseOperation_ttransA,intmb,intnnzb,constcuDoubleComplex*alpha,constcusparseMatDescr_tdescrA,constcuDoubleComplex*bsrValA,constint*bsrRowPtrA,constint*bsrColIndA,intblockDim,bsrsv2Info_tinfo,constcuDoubleComplex*x,cuDoubleComplex*y,cusparseSolvePolicy_tpolicy,void*pBuffer)

This function performs the solve phase ofbsrsv2, a new sparse triangular linear systemop(A)*y=\(\alpha\)x.