muSPARSE API Reference

This reference covers the muSPARSE APIs supported in MUSA SDK 5.2. It introduces the sparse data model, descriptor model, and execution workflow, presents storage formats as a separate chapter, and organizes the supported APIs into Basic, Legacy, and Generic chapters that follow the cuSPARSE document structure within the MUSA SDK 5.2 scope.

1. Introduction

1.1 What Is muSPARSE

muSPARSE provides GPU-accelerated sparse linear algebra routines for MUSA devices. The library combines two programming models:

• APIs that use raw arrays together with musparseMatDescr_t
• generic APIs that use dense and sparse vector or matrix descriptors

The generic APIs are the main way to express sparse vector operations, sparse matrix-vector operations, sparse matrix-matrix operations, and sparse-dense conversion workflows in this release.

1.2 Document Scope in MUSA SDK 5.2

Use this reference to verify the muSPARSE functions, types, parameters, storage conventions, and status values supported in MUSA SDK 5.2.

Note: Some muSPARSE declarations may appear in the public headers but are absent from this reference. These declarations are experimental in MUSA SDK 5.2 and are provided for reference only.

1.3 Supported API Groups

API chapter	Supported APIs	Coverage in this reference
Basic APIs	musparseCreate, musparseDestroy, musparseSetStream, musparseGetStream, musparseSetPointerMode, musparseGetPointerMode	Detailed function entries
Legacy APIs	musparseCreateMatDescr, musparseDestroyMatDescr, musparseGetMatIndexBase, musparseGetMatType, musparseGetMatFillMode, musparseGetMatDiagType	Detailed function entries
Generic APIs	musparseCreateDnVec, musparseDestroyDnVec, musparseAxpby, musparseSpVV, musparseCreateCsr, musparseSpMV, musparseSpMM, musparseSparseToDense	Types, descriptor constructors, scoped compute APIs, and detailed function entries

1.4 How to Use This Document

Start with Chapter 2 to understand the muSPARSE data model, descriptor roles, and workspace behavior. Use Chapter 3 for storage conventions, Chapter 4 for basic status and management APIs, Chapter 5 for legacy matrix-descriptor material, and Chapter 6 for the generic APIs covered by this reference.

2. Using the muSPARSE API

2.1 Sparse Data Model

muSPARSE operates on vectors and matrices in which only nonzero entries are stored explicitly. The generic API uses descriptors to describe those sparse objects and the dense inputs or outputs they interact with.

Typical sparse workflows in this reference include:

$$\mathrm{result} := op(x) \cdot y$$ $$y := \alpha \cdot op(A) \cdot x + \beta \cdot y$$ $$op(A) \cdot y = \alpha \cdot x$$ $$C := \alpha \cdot op(A) \cdot op(B) + \beta \cdot C$$ $$C' := \alpha \cdot op(A) \cdot op(B) + \beta \cdot C$$

Here, A, B, and C may be sparse or dense depending on the API family, C' is the updated output for helper families that accumulate through matC, x and y are vectors, and op(.) selects the original, transposed, or conjugate-transposed form.

The op(A) \cdot y = \alpha \cdot x and C' := \alpha \cdot op(A) \cdot op(B) + \beta \cdot C forms are included as conceptual background only. The related helper families are experimental in MUSA SDK 5.2 and are not part of the published API scope of this reference.

2.2 Handles, Streams, And Pointer Mode

Every muSPARSE routine covered here takes a musparseHandle_t library context handle. The handle identifies the execution context used by the library call.

The management API also controls:

• the MUSA stream associated with the handle
• whether scalar pointer arguments are read from host memory or device memory

Use musparseSetStream and musparseGetStream to bind or query the stream. Use musparseSetPointerMode and musparseGetPointerMode to control whether scalar arguments such as alpha, beta, or result pointers are interpreted in host or device memory.

2.3 Generic Dense And Sparse Descriptors

The generic API uses descriptors instead of raw shape and pointer bundles.

Descriptor type	Role
musparseDnVecDescr_t	Dense vector descriptor
musparseSpVecDescr_t	Sparse vector descriptor
musparseDnMatDescr_t	Dense matrix descriptor
musparseSpMatDescr_t	Sparse matrix descriptor

The generic descriptor-constructor coverage in this reference directly includes dense vectors and CSR sparse matrices. Later operation sections use the same descriptor model for dense matrices, sparse matrices, and sparse vectors in compute or conversion routines. This reference documents CSR in detail. The musparseSparseToDense API covered here accepts sparse matrix descriptors in CSR, COO, or CSC format.

2.4 Workspace And Staged Execution

Several muSPARSE operations require caller-provided temporary storage.

In the published API scope of this reference, the compute APIs that use caller-managed workspace are:

• musparseSpVV
• musparseSpMV
• musparseSpMM
• musparseSparseToDense

The public header also declares companion helpers for workspace queries, preprocessing, analysis, or staged conversion. Those helper declarations are experimental in MUSA SDK 5.2 and are not part of the published API scope of this reference.

When a workflow includes preprocessing, keep the sparse structure unchanged between preprocess and compute steps. If the sparsity pattern changes, the previously prepared metadata or temporary storage assumptions may no longer be valid.

2.5 Generic Sparse Vector Operations

The sparse vector operations covered here use descriptor-based inputs rather than typed raw-array entry points.

The vector-level kernels covered here are:

• musparseAxpby, which updates a dense vector from a sparse vector
• musparseSpVV, which computes a sparse-dense inner product using caller-managed workspace

These routines use dense and sparse vector descriptors together with a compute data type and, in some cases, caller-managed workspace.

2.6 Generic Sparse Matrix-Vector Operations

The matrix-vector section covers sparse matrix-vector multiplication.

In the generic API naming used here, SpMV means sparse matrix-vector multiplication.

For multiplication, the core operation is:

$$y := \alpha \cdot op(A) \cdot x + \beta \cdot y$$

For conceptual background only, the public header also contains sparse triangular solve families with the following problem form:

$$op(A) \cdot y = \alpha \cdot x$$

This equation is included for reference only and does not indicate that the related API family is in the current published scope of this document.

The API in this family is:

• musparseSpMV, which uses caller-managed workspace

2.7 Generic Sparse Matrix-Matrix Operations

The matrix-matrix section covers sparse-dense multiplication.

The main problem forms are:

$$C := \alpha \cdot op(A) \cdot op(B) + \beta \cdot C$$

For conceptual background only, the public header also contains related generic families with the following problem forms:

$$op(A) \cdot C = \alpha \cdot op(B)$$ $$C' := \alpha \cdot op(A) \cdot op(B) + \beta \cdot C$$

These equations are included for reference only and do not indicate that the related API families are in the current published scope of this document.

The API in this family is:

• musparseSpMM, which uses caller-managed workspace

The public header also contains other generic matrix helper families, but they are experimental in MUSA SDK 5.2 and are not part of the published API scope of this reference.

2.8 Sparse-Dense Conversion

The conversion section covers movement from sparse matrices to dense matrix representations in the published API scope of this reference.

• musparseSparseToDense converts a sparse matrix descriptor into a dense matrix descriptor using caller-managed workspace

The public header also declares reverse conversion helpers for dense-to-sparse workflows, but they are experimental in MUSA SDK 5.2 and are not part of the published API scope of this reference.

The sparse-dense conversion helper families support CSR, COO, and CSC sparse matrix descriptors. This scoped reference describes CSR in detail because CSR is the sparse matrix constructor covered by the published API scope. COO and CSC are standard sparse matrix formats accepted by the conversion helpers, but this reference does not expand them as separate storage-format sections.

2.9 Error Handling

All functions covered here return musparseStatus_t. A return value of MUSPARSE_STATUS_SUCCESS indicates that the API call completed successfully.

Depending on the API family, non-success returns can report:

• invalid values or unsupported configurations
• allocation, execution, or internal failures
• unsupported matrix types

3. muSPARSE Storage Formats

The muSPARSE APIs covered in MUSA SDK 5.2 use a focused subset of the full header-level storage model. This chapter describes the formats and descriptor conventions needed for:

• dense vectors
• sparse vectors
• dense matrices
• CSR sparse matrices
• musparseMatDescr_t used by raw-array sparse APIs

3.1 Index Base

muSPARSE supports both zero-based and one-based indexing through musparseIndexBase_t.

Value	Meaning
MUSPARSE_INDEX_BASE_ZERO	The first logical entry has index 0.
MUSPARSE_INDEX_BASE_ONE	The first logical entry has index 1.

For CSR matrices, the index base applies to the column index array and to the row offset array. Legacy matrix descriptors store the selected base explicitly.

3.2 Vector Formats

3.2.1 Dense Vector Format

Dense vectors are stored linearly in memory. A dense vector descriptor records the vector length, the element pointer, and the element data type.

For a length-n vector

$$x = \begin{bmatrix} x_1 \\ x_2 \\ \vdots \\ x_n \end{bmatrix}$$

the storage order is:

$$[x_1, x_2, \ldots, x_n]$$

3.2.2 Sparse Vector Format

Sparse vectors are represented by an index array and a value array. If the vector has nnz stored entries, then the representation is:

$$\text{indices} = [i_1, i_2, \ldots, i_{nnz}], \quad \text{values} = [x_{i_1}, x_{i_2}, \ldots, x_{i_{nnz}}]$$

The generic sparse vector operations in this reference use sparse vector descriptors together with dense vector descriptors.

3.3 Matrix Formats

3.3.1 CSR Format

The sparse matrix format described explicitly in this reference is compressed sparse row (CSR). COO and CSC descriptors can be used by the sparse-dense conversion helper families documented in Chapter 6, but their format layouts are not expanded as standalone sections in this scoped reference. A CSR matrix with m rows, n columns, and nnz stored values uses:

• a row offset array of length m + 1
• a column index array of length nnz
• a value array of length nnz

For row r, the stored entries are found in:

$$\text{row\_ptr}[r] \leq j < \text{row\_ptr}[r+1]$$

The corresponding column of the jth stored entry is col_ind[j], and its value is val[j].

3.3.2 Dense Matrix Format

Dense matrix descriptors describe full matrices used by the SpMM, SpSM, sparse-to-dense, and dense-to-sparse helper families documented in Chapter 6.

The layout is described by musparseOrder_t:

Value	Meaning
MUSPARSE_ORDER_COL	Column-major dense storage
MUSPARSE_ORDER_ROW	Row-major dense storage

When reading a dense matrix descriptor, pay attention to the matrix dimensions, leading dimension, and the selected order.

3.3.3 Matrix Descriptor Semantics

The musparseMatDescr_t model describes structural properties of a sparse matrix independently of its raw index and value arrays. The descriptor can record:

• index base
• matrix type
• fill mode
• diagonal type

This model is used by the matrix descriptor APIs and by raw-array sparse workflows that need structural metadata in addition to the sparse storage arrays.

4. muSPARSE Basic APIs

This chapter describes the shared status values, basic public types, and management routines used across the muSPARSE APIs covered in this reference.

4.1 Return Value musparseStatus_t

The functions in this reference return musparseStatus_t. A return value of MUSPARSE_STATUS_SUCCESS indicates that the call completed successfully. Any other value indicates that the call did not complete as requested.

Status value	Meaning
MUSPARSE_STATUS_SUCCESS	The operation completed successfully.
MUSPARSE_STATUS_NOT_INITIALIZED	The library context or descriptor state was not initialized.
MUSPARSE_STATUS_ALLOC_FAILED	An internal allocation failed.
MUSPARSE_STATUS_INVALID_VALUE	One or more argument values are invalid.
MUSPARSE_STATUS_ARCH_MISMATCH	The selected device architecture does not support the requested operation.
MUSPARSE_STATUS_EXECUTION_FAILED	Device execution failed.
MUSPARSE_STATUS_INTERNAL_ERROR	The library encountered an internal failure.
MUSPARSE_STATUS_MATRIX_TYPE_NOT_SUPPORTED	The selected matrix type is not supported by the routine.
MUSPARSE_STATUS_ZERO_PIVOT	A structural or numerical zero pivot was detected.
MUSPARSE_STATUS_NOT_SUPPORTED	The requested operation or configuration is not supported.
MUSPARSE_STATUS_INSUFFICIENT_RESOURCES	The operation could not proceed because the available resources were insufficient.

The public enum also defines compatibility aliases such as MUSPARSE_STATUS_INVALID_HANDLE, MUSPARSE_STATUS_INVALID_POINTER, MUSPARSE_STATUS_INVALID_SIZE, MUSPARSE_STATUS_TYPE_MISMATCH, and MUSPARSE_STATUS_REQUIRES_SORTED_STORAGE. In the current public type definition, those aliases map to MUSPARSE_STATUS_INVALID_VALUE.

4.2 Basic Types Reference

This section summarizes the basic public types used by the management APIs in this reference.

Type	Purpose
musparseHandle_t	Library context handle passed to each muSPARSE API.
musparseStatus_t	Return type used by the muSPARSE functions in this reference.
musparsePointerMode_t	Selects whether scalar pointers are interpreted in host or device memory.
musaStream_t	MUSA stream type associated with a muSPARSE handle.

4.2.1 musparsePointerMode_t

Value	Meaning
MUSPARSE_POINTER_MODE_HOST	Scalar pointers refer to host memory.
MUSPARSE_POINTER_MODE_DEVICE	Scalar pointers refer to device memory.

4.3 Management API

The management API creates and destroys the muSPARSE library context and controls the stream and pointer mode bound to that context.

4.3.1 musparseCreate

musparseStatus_t musparseCreate(musparseHandle_t* handle)

Initializes a muSPARSE library context.

Parameter	Description
handle	Output pointer that receives the initialized muSPARSE handle.

Returns MUSPARSE_STATUS_SUCCESS on success. Reported failure modes include MUSPARSE_STATUS_INVALID_HANDLE and MUSPARSE_STATUS_INTERNAL_ERROR.

4.3.2 musparseDestroy

musparseStatus_t musparseDestroy(musparseHandle_t handle)

Destroys a muSPARSE library context and releases the resources associated with it.

Parameter	Description
handle	The muSPARSE handle to destroy.

Returns MUSPARSE_STATUS_SUCCESS on success. Reported failure modes include MUSPARSE_STATUS_INVALID_HANDLE and MUSPARSE_STATUS_INTERNAL_ERROR.

4.3.3 musparseSetStream

musparseStatus_t musparseSetStream(musparseHandle_t handle, musaStream_t stream)

Associates a user-defined MUSA stream with the specified muSPARSE handle. Subsequent operations submitted through that handle use the selected stream.

Parameter	Description
handle	The muSPARSE handle whose stream association will be updated.
stream	The MUSA stream to associate with the handle.

Returns MUSPARSE_STATUS_SUCCESS on success. The reported failure mode is MUSPARSE_STATUS_INVALID_HANDLE.

4.3.4 musparseGetStream

musparseStatus_t musparseGetStream(musparseHandle_t handle, musaStream_t* stream)

Queries the MUSA stream currently associated with the specified muSPARSE handle.

Parameter	Description
handle	The muSPARSE handle to query.
stream	Output pointer that receives the current stream.

Returns MUSPARSE_STATUS_SUCCESS on success. The reported failure mode is MUSPARSE_STATUS_INVALID_HANDLE.

4.3.5 musparseSetPointerMode

musparseStatus_t musparseSetPointerMode(musparseHandle_t handle, musparsePointerMode_t pointer_mode)

Selects whether scalar pointer arguments associated with the handle are interpreted in host memory or device memory.

Parameter	Description
handle	The muSPARSE handle whose pointer mode will be updated.
pointer_mode	The new pointer mode, such as MUSPARSE_POINTER_MODE_HOST or MUSPARSE_POINTER_MODE_DEVICE.

Returns MUSPARSE_STATUS_SUCCESS on success. The reported failure mode is MUSPARSE_STATUS_INVALID_HANDLE.

4.3.6 musparseGetPointerMode

musparseStatus_t musparseGetPointerMode(musparseHandle_t handle, musparsePointerMode_t* pointer_mode)

Queries the current pointer mode associated with the specified muSPARSE handle.

Parameter	Description
handle	The muSPARSE handle to query.
pointer_mode	Output pointer that receives the current pointer mode.

Returns MUSPARSE_STATUS_SUCCESS on success. The reported failure mode is MUSPARSE_STATUS_INVALID_HANDLE.

5. muSPARSE Legacy APIs

This chapter follows the cuSPARSE public taxonomy. Here, Legacy APIs refers to the matrix-descriptor-based public APIs included in this MUSA SDK 5.2 reference. It does not mean deprecated, and it does not refer to the internal compatibility-only APIs that remain outside this document. Unlike the generic APIs in Chapter 6, this model centers on musparseMatDescr_t and related enums that describe sparse matrix structure through shared metadata.

5.1 Legacy Scope Note

Use this chapter for the matrix-descriptor model centered on musparseMatDescr_t. These APIs describe sparse matrix structure through metadata such as index base, matrix type, fill mode, and diagonal type.

5.2 Legacy Types Reference

This section summarizes the legacy-style public types used by the matrix-descriptor APIs in this reference.

Type	Purpose
musparseMatDescr_t	Opaque descriptor handle that stores sparse matrix structural metadata.
musparseIndexBase_t	Selects zero-based or one-based sparse indexing.
musparseMatrixType_t	Records the structural matrix class stored in a descriptor.
musparseFillMode_t	Records whether lower or upper triangular data is interpreted.
musparseDiagType_t	Records whether the diagonal is treated as unit or non-unit.

5.2.1 musparseIndexBase_t

Value	Meaning
MUSPARSE_INDEX_BASE_ZERO	The first logical sparse index is 0.
MUSPARSE_INDEX_BASE_ONE	The first logical sparse index is 1.

5.2.2 Matrix Descriptor Enums

Enum type	Supported values	Meaning
musparseMatrixType_t	MUSPARSE_MATRIX_TYPE_GENERAL, MUSPARSE_MATRIX_TYPE_SYMMETRIC, MUSPARSE_MATRIX_TYPE_HERMITIAN, MUSPARSE_MATRIX_TYPE_TRIANGULAR	Structural matrix class recorded in the descriptor.
musparseFillMode_t	MUSPARSE_FILL_MODE_LOWER, MUSPARSE_FILL_MODE_UPPER	Which triangular part is stored or interpreted.
musparseDiagType_t	MUSPARSE_DIAG_TYPE_NON_UNIT, MUSPARSE_DIAG_TYPE_UNIT	Whether diagonal values are stored explicitly or treated as implicit ones.

5.3 Matrix Descriptor API

The matrix descriptor API exposes the musparseMatDescr_t model used by raw-array sparse workflows. A musparseMatDescr_t stores structural metadata rather than the sparse arrays themselves.

5.3.1 musparseCreateMatDescr

musparseStatus_t musparseCreateMatDescr(musparseMatDescr_t* descr)

Creates a matrix descriptor. The documented defaults are:

• matrix type: MUSPARSE_MATRIX_TYPE_GENERAL
• index base: MUSPARSE_INDEX_BASE_ZERO

Parameter	Description
descr	Output pointer that receives the matrix descriptor.

Returns MUSPARSE_STATUS_SUCCESS on success. The reported failure mode is MUSPARSE_STATUS_INVALID_POINTER.

5.3.2 musparseDestroyMatDescr

musparseStatus_t musparseDestroyMatDescr(musparseMatDescr_t descr)

Destroys a matrix descriptor and releases its resources.

Parameter	Description
descr	The matrix descriptor to destroy.

Returns MUSPARSE_STATUS_SUCCESS on success. The reported failure mode is MUSPARSE_STATUS_INVALID_POINTER.

5.3.3 musparseGetMatIndexBase

musparseIndexBase_t musparseGetMatIndexBase(const musparseMatDescr_t descr)

Returns the index base recorded in a matrix descriptor.

Parameter	Description
descr	The matrix descriptor to query.

Returns either MUSPARSE_INDEX_BASE_ZERO or MUSPARSE_INDEX_BASE_ONE.

5.3.4 musparseGetMatType

musparseMatrixType_t musparseGetMatType(const musparseMatDescr_t descr)

Returns the structural matrix type recorded in a matrix descriptor.

Parameter	Description
descr	The matrix descriptor to query.

Returns one of MUSPARSE_MATRIX_TYPE_GENERAL, MUSPARSE_MATRIX_TYPE_SYMMETRIC, MUSPARSE_MATRIX_TYPE_HERMITIAN, or MUSPARSE_MATRIX_TYPE_TRIANGULAR.

5.3.5 musparseGetMatFillMode

musparseFillMode_t musparseGetMatFillMode(const musparseMatDescr_t descr)

Returns the fill mode recorded in a matrix descriptor.

Parameter	Description
descr	The matrix descriptor to query.

Returns either MUSPARSE_FILL_MODE_LOWER or MUSPARSE_FILL_MODE_UPPER.

5.3.6 musparseGetMatDiagType

musparseDiagType_t musparseGetMatDiagType(const musparseMatDescr_t descr)

Returns the diagonal type recorded in a matrix descriptor.

Parameter	Description
descr	The matrix descriptor to query.

Returns either MUSPARSE_DIAG_TYPE_NON_UNIT or MUSPARSE_DIAG_TYPE_UNIT.

6. muSPARSE Generic APIs

This chapter follows the declarations exported by musparse.h. When the header exposes a workflow through helper functions, this reference uses those helper names directly instead of introducing a nonexistent single-call placeholder.

6.1 Generic Types Reference

Some generic descriptor types appear in supported compute signatures even when the corresponding constructor or query routines are outside the scope of this reference. The type overview below keeps the later workflow sections readable.

Type	Purpose
musparseDnVecDescr_t	Dense vector descriptor type.
musparseSpVecDescr_t	Sparse vector descriptor type.
musparseDnMatDescr_t	Dense matrix descriptor type.
musparseSpMatDescr_t	Sparse matrix descriptor type.
musparseConstDnVecDescr_t	Const-qualified dense vector descriptor type used by generic compute routines.
musparseConstSpVecDescr_t	Const-qualified sparse vector descriptor type used by generic compute routines.
musparseConstDnMatDescr_t	Const-qualified dense matrix descriptor type used by generic compute routines.
musparseConstSpMatDescr_t	Const-qualified sparse matrix descriptor type used by generic compute routines.
musparseIndexType_t	Integer width used by sparse index arrays.
musparseDataType_t	Scalar data type attached to descriptors and compute routines.
musaDataType	Scalar compute type used by several generic compute routines.
musparseOperation_t	Selects the original, transposed, or conjugate-transposed interpretation of an operand.
musparseOrder_t	Selects row-major or column-major dense matrix layout.

The generic CSR constructor also uses musparseIndexBase_t, introduced in Chapter 5, to select zero-based or one-based sparse indexing.

6.1.1 musparseOperation_t

Value	Meaning
MUSPARSE_OPERATION_NON_TRANSPOSE	Use the operand without transposition.
MUSPARSE_OPERATION_TRANSPOSE	Use the transpose of the operand.
MUSPARSE_OPERATION_CONJUGATE_TRANSPOSE	Use the conjugate transpose of the operand.

6.1.2 Algorithm Types

Type	Role
musparseSpMVAlg_t	Selects the sparse matrix-vector multiplication algorithm.
musparseSpMMAlg_t	Selects the sparse-dense matrix multiplication algorithm.
musparseSparseToDenseAlg_t	Selects the sparse-to-dense conversion algorithm.

The public header also defines additional algorithm or stage types for helper families that are experimental in MUSA SDK 5.2 and are not part of the published API scope of this reference.

6.2 Dense Vector APIs

This section covers the dense vector descriptor constructors included in this reference.

6.2.1 musparseCreateDnVec

musparseStatus_t musparseCreateDnVec(musparseDnVecDescr_t* descr, int64_t size,
                                     void* values,
                                     musparseDataType_t data_type)

Creates a dense vector descriptor.

Parameter	Description
descr	Output pointer that receives the dense vector descriptor.
size	Logical length of the dense vector.
values	Pointer to the dense vector values.
data_type	Scalar type stored in the dense vector.

Returns MUSPARSE_STATUS_SUCCESS on success. Reported failure modes include MUSPARSE_STATUS_INVALID_POINTER, MUSPARSE_STATUS_INVALID_SIZE, and MUSPARSE_STATUS_INVALID_VALUE.

6.2.2 musparseDestroyDnVec

musparseStatus_t musparseDestroyDnVec(musparseConstDnVecDescr_t descr)

Destroys a dense vector descriptor and releases its resources.

Parameter	Description
descr	The dense vector descriptor to destroy.

Returns MUSPARSE_STATUS_SUCCESS on success. The reported failure mode is MUSPARSE_STATUS_INVALID_POINTER.

6.3 Sparse Vector APIs

This section covers the sparse vector routines included in this reference. The compute APIs use descriptor-based sparse and dense vector operands, even though the sparse vector constructor APIs themselves are outside the scope of this reference.

6.3.1 musparseAxpby

musparseStatus_t musparseAxpby(musparseHandle_t handle, const void* alpha,
                               musparseConstSpVecDescr_t x, const void* beta,
                               musparseDnVecDescr_t y)

Updates the dense vector y from the sparse vector x using the scalar coefficients alpha and beta. The active pointer mode determines whether the scalar pointers are read from host memory or device memory.

Parameter	Description
handle	muSPARSE library context.
alpha	Scalar multiplier applied to the stored values of x.
x	Sparse vector descriptor that provides the updated indices and values.
beta	Scalar multiplier applied to the existing values of y.
y	Dense vector descriptor updated in place.

Returns MUSPARSE_STATUS_SUCCESS on success. Non-success returns indicate an invalid handle or invalid input pointers.

6.3.2 musparseSpVV

musparseStatus_t musparseSpVV(
    musparseHandle_t handle, musparseOperation_t opX,
    musparseConstSpVecDescr_t vecX, musparseConstDnVecDescr_t vecY,
    void* result, musaDataType computeType, void* externalBuffer);

This workflow computes the sparse-dense inner product

$$\mathrm{result} := op(x) \cdot y$$

with op(x) selected by opX.

This operation uses caller-provided workspace through externalBuffer. The related workspace-query helper declared in the public header is experimental in MUSA SDK 5.2 and is not part of the published API scope of this reference.

The result pointer follows the active pointer and data-type conventions for the selected compute type.

6.4 Sparse Matrix APIs

The sparse matrix constructor coverage in this reference is limited to CSR.

6.4.1 musparseCreateCsr

musparseStatus_t musparseCreateCsr(musparseSpMatDescr_t* descr, int64_t rows,
                                   int64_t cols, int64_t nnz, void* csr_row_ptr,
                                   void* csr_col_ind, void* csr_val,
                                   musparseIndexType_t row_ptr_type,
                                   musparseIndexType_t col_ind_type,
                                   musparseIndexBase_t idx_base,
                                   musparseDataType_t data_type)

Creates a sparse matrix descriptor for a CSR matrix.

Parameter	Description
descr	Output pointer that receives the sparse CSR matrix descriptor.
rows	Number of rows in the CSR matrix.
cols	Number of columns in the CSR matrix.
nnz	Number of stored nonzero entries.
csr_row_ptr	Pointer to the row offset array of length rows + 1.
csr_col_ind	Pointer to the column index array of length nnz.
csr_val	Pointer to the value array of length nnz.
row_ptr_type	Index type used by the row offset array, such as MUSPARSE_INDEX_32I or MUSPARSE_INDEX_64I.
col_ind_type	Index type used by the column index array, such as MUSPARSE_INDEX_32I or MUSPARSE_INDEX_64I.
idx_base	Sparse index base, either zero-based or one-based.
data_type	Scalar type stored in the value array.

Returns MUSPARSE_STATUS_SUCCESS on success. Reported failure modes include MUSPARSE_STATUS_INVALID_POINTER, MUSPARSE_STATUS_INVALID_SIZE, and MUSPARSE_STATUS_INVALID_VALUE.

6.5 Generic Matrix And Conversion APIs

This section records the descriptor-based matrix and conversion APIs that are in the published API scope of this reference. The public header also declares companion helpers for workspace queries or preprocessing, but those declarations are not expanded as formal API entries here.

6.5.1 musparseSpMV

musparseStatus_t musparseSpMV(
    musparseHandle_t handle, musparseOperation_t trans, const void* alpha,
    musparseConstSpMatDescr_t mat, musparseConstDnVecDescr_t x,
    const void* beta, musparseDnVecDescr_t y,
    musparseDataType_t compute_type, musparseSpMVAlg_t alg,
    void* temp_buffer);

This API implements sparse matrix-vector multiplication:

$$y := \alpha \cdot op(A) \cdot x + \beta \cdot y$$

This operation uses caller-managed workspace through temp_buffer. The related workspace-query and preprocess helpers declared in the public header are experimental in MUSA SDK 5.2 and are not part of the published API scope of this reference.

6.5.2 musparseSpMM

musparseStatus_t musparseSpMM(
    musparseHandle_t handle, musparseOperation_t opA,
    musparseOperation_t opB, const void* alpha,
    musparseConstSpMatDescr_t matA, musparseConstDnMatDescr_t matB,
    const void* beta, musparseDnMatDescr_t matC,
    musaDataType computeType, musparseSpMMAlg_t alg,
    void* externalBuffer);

This API implements sparse-dense matrix multiplication:

$$C := \alpha \cdot op(A) \cdot op(B) + \beta \cdot C$$

This operation uses caller-managed workspace through externalBuffer. The related workspace-query and preprocess helpers declared in the public header are experimental in MUSA SDK 5.2 and are not part of the published API scope of this reference.

6.5.3 musparseSparseToDense

musparseStatus_t musparseSparseToDense(
    musparseHandle_t handle, musparseConstSpMatDescr_t matA,
    musparseDnMatDescr_t matB, musparseSparseToDenseAlg_t alg,
    void* externalBuffer);

This API converts a sparse matrix descriptor into a dense matrix descriptor.

This operation uses caller-managed workspace through externalBuffer. The related workspace-query helper declared in the public header is experimental in MUSA SDK 5.2 and is not part of the published API scope of this reference.

The sparse input descriptor can use CSR, COO, or CSC format.