Function sddmm 

pub fn sddmm<Compute: DataTypeLike>(
    ctx: &Context,
    op_a: Operation,
    op_b: Operation,
    alpha: Scalar<'_, Compute>,
    matrix_a: &DenseMatrixDescriptor<'_>,
    matrix_b: &DenseMatrixDescriptor<'_>,
    beta: Scalar<'_, Compute>,
    matrix_c: &mut SparseMatrixDescriptor<'_>,
    algorithm: SddmmAlgorithm,
    external_buffer: Option<DevicePtr>,
) -> Result<()>

Multiplies matrix_a and matrix_b, then applies the sparsity pattern of matrix_c. Formally, it computes $C = \alpha (op(A) op(B)) \circ spy(C) + \beta C$, where:

• op(A) is a dense matrix of size $m \times k$.
• op(B) is a dense matrix of size $k \times n$.
• C is a sparse matrix of size $m \times n$.
• alpha and beta are scalars.
• $\circ$ denotes the Hadamard (entry-wise) matrix product, and spy(C) is the structural sparsity pattern of C, equal to 1 where C stores an entry and 0 elsewhere.

op(A) is selected by op_a and may be A, A^T, or A^H. op(B) is selected by op_b and may be B, B^T, or B^H.

sddmm_buffer_size returns the workspace size needed by sddmm or sddmm_preprocess.

Calling sddmm_preprocess is optional. It may accelerate subsequent calls to sddmm. Useful when sddmm is called multiple times with the same sparsity pattern (matrix_c).

Calling sddmm_preprocess with buffer makes that buffer active for matrix_c SDDMM calls. Subsequent calls to sddmm with matrix_c and the active buffer must use the same values for all parameters as the call to sddmm_preprocess. The exceptions are: alpha, beta, matrix_a, matrix_b, and the values (but not indices) of matrix_c may be different. Importantly, the buffer contents must be unmodified since the call to sddmm_preprocess. When sddmm is called with matrix_c and its active buffer, it may read acceleration data from the buffer.

Calling sddmm_preprocess again with matrix_c and a new buffer makes the new buffer active and makes the previously active buffer inactive. For sddmm, there can only be one active buffer per sparse matrix at a time. To get the effect of multiple active buffers for a single sparse matrix, create multiple matrix handles that all point to the same index and value buffers, and call sddmm_preprocess once per handle with different workspace buffers.

Calling sddmm with an inactive buffer is always permitted. However, there may be no acceleration from the preprocessing in that case.

For the purposes of thread safety, sddmm_preprocess is writing to matrix_c internal state.

Currently supported sparse matrix formats:

• Format::Csr
• Format::Bsr

sddmm supports the following index type for representing matrix_c:

• 32-bit indices (IndexType::I32)
• 64-bit indices (IndexType::I64)

The data type combinations currently supported for sddmm are listed below:

Uniform-precision computation:

A/B/C/compute_type
DataType::F32
DataType::F64
DataType::ComplexF32
DataType::ComplexF64

Mixed-precision computation:

A/B	C	compute_type
DataType::F16	DataType::F32	DataType::F32
DataType::F16	DataType::F16

sddmm for Format::Bsr also supports the following mixed-precision computation:

A/B	C	compute_type
DataType::Bf16	DataType::F32	DataType::F32
DataType::Bf16	DataType::Bf16

DataType::F16 and DataType::Bf16 always imply mixed-precision computation.

sddmm for Format::Bsr supports block sizes of 2, 4, 8, 16, 32, 64 and 128.

sddmm supports the following algorithms:

Algorithm	Notes
SddmmAlgorithm::Default	Default algorithm.

It supports batched computation.

Performance notes: sddmm for Format::Csr provides the best performance when matrix_a and matrix_b satisfy:

• For matrix_a:

  • matrix_a is in row-major order and op_a is Operation::NonTranspose, or
  • matrix_a is in col-major order and op_a is not Operation::NonTranspose.

• For matrix_b:

  • matrix_b is in col-major order and op_b is Operation::NonTranspose, or
  • matrix_b is in row-major order and op_b is not Operation::NonTranspose.

sddmm for Format::Bsr provides the best performance when matrix_a and matrix_b satisfy:

• For matrix_a:

  • matrix_a is in row-major order and op_a is Operation::NonTranspose, or
  • matrix_a is in col-major order and op_a is not Operation::NonTranspose.

• For matrix_b:

  • matrix_b is in row-major order and op_b is Operation::NonTranspose, or
  • matrix_b is in col-major order and op_b is not Operation::NonTranspose.

sddmm supports the following batch modes:

• $C_{i} = (A \cdot B) \circ C_{i}$
• $C_{i} = \left( A_{i} \cdot B \right) \circ C_{i}$
• $C_{i} = \left( A \cdot B_{i} \right) \circ C_{i}$
• $C_{i} = \left( A_{i} \cdot B_{i} \right) \circ C_{i}$

The number of batches and their strides can be set by using SparseMatrixDescriptor::set_csr_strided_batch and DenseMatrixDescriptor::set_strided_batch. The maximum number of batches for sddmm is 65,535.

sddmm has the following properties:

• Requires no extra storage.
• Provides deterministic (bitwise) results for each run.
• Supports asynchronous execution.
• Allows the indices of matrix_c to be unsorted.

sddmm supports the following optimizations:

• CUDA graph capture.
• Hardware Memory Compression.