Skip to main content
`Ctrl`+`K`

# Matrix multiply (matmul) functions

hipSPARSELt: Matrix multiply (matmul) functions
Functions
Matrix multiply (matmul) functions

## Functions

hipsparseStatus_t | hipsparseLtMatmulGetWorkspace (const hipsparseLtHandle_t *handle, const hipsparseLtMatmulPlan_t *plan, size_t *workspaceSize)
| Determines the required workspace size.
hipsparseStatus_t | hipsparseLtMatmulPlanInit (const hipsparseLtHandle_t *handle, hipsparseLtMatmulPlan_t *plan, const hipsparseLtMatmulDescriptor_t *matmulDescr, const hipsparseLtMatmulAlgSelection_t *algSelection)
| Initializes the matrix multiplication plan descriptor.
hipsparseStatus_t | hipsparseLtMatmulPlanDestroy (const hipsparseLtMatmulPlan_t *plan)
| Destroy a matrix multiplication plan descriptor.
hipsparseStatus_t | hipsparseLtMatmul (const hipsparseLtHandle_t *handle, const hipsparseLtMatmulPlan_t *plan, const void *alpha, const void *d_A, const void *d_B, const void *beta, const void *d_C, void *d_D, void *workspace, hipStream_t *streams, int32_t numStreams)
| Sparse matrix dense matrix multiplication.
hipsparseStatus_t | hipsparseLtMatmulSearch (const hipsparseLtHandle_t *handle, hipsparseLtMatmulPlan_t *plan, const void *alpha, const void *d_A, const void *d_B, const void *beta, const void *d_C, void *d_D, void *workspace, hipStream_t *streams, int32_t numStreams)
| Sparse matrix dense matrix multiplication.

## Detailed Description

Multiplies sparse matrices

## Function Documentation

## ◆ hipsparseLtMatmul()

hipsparseStatus_t hipsparseLtMatmul | ( | const hipsparseLtHandle_t * | handle,
|  | const hipsparseLtMatmulPlan_t * | plan,
|  | const void * | alpha,
|  | const void * | d_A,
|  | const void * | d_B,
|  | const void * | beta,
|  | const void * | d_C,
|  | void * | d_D,
|  | void * | workspace,
|  | hipStream_t * | streams,
|  | int32_t | numStreams )

Sparse matrix dense matrix multiplication.

`hipsparseLtMatmul` computes the matrix multiplication of matrices A and B to produce the output matrix D, according to the following operation:

\[ D := Activation(\alpha \cdot op(A) \cdot op(B) + \beta \cdot C + bias) * scale \]

Note
  This function is non blocking and executed asynchronously with respect to the host. It may return before the actual computation has finished.
  Currently, only supports the case where D has the same shape of C.

Parameters

  [in] | handle | hipsparselt library handle
  [in] | plan | Matrix multiplication plan
  [in] | alpha | scalar \(\alpha\). (float)
  [in] | d_A | Pointer to the structured matrix A
  [in] | d_B | Pointer to the dense matrix B
  [in] | beta | scalar \(\beta\). (float)
  [in] | d_C | Pointer to the dense matrix C
  [out] | d_D | Pointer to the dense matrix D
  [in] | workspace | Pointor to the worksapce
  [in] | streams | Pointer to HIP stream array for the computation
  [in] | numStreams | Number of HIP streams in `streams`

Return values

  HIPSPARSE_STATUS_SUCCESS | the operation completed successfully.
  HIPSPARSE_STATUS_NOT_INITIALIZED | `handle` or `plan` is invalid.
  HIPSPARSE_STATUS_INVALID_VALUE | `handle`, `plan` `alpha`, `d_A`, `d_B`, `beta`, `d_C` , `d_D` , `workspace` `streams` or `numStreams` is invalid.
  HIPSPARSE_STATUS_NOT_SUPPORTED | the problme is not supported.

## ◆ hipsparseLtMatmulGetWorkspace()

hipsparseStatus_t hipsparseLtMatmulGetWorkspace | ( | const hipsparseLtHandle_t * | handle,
|  | const hipsparseLtMatmulPlan_t * | plan,
|  | size_t * | workspaceSize )

Determines the required workspace size.

`hipsparseLtMatmulGetWorkspace` determines the required workspace size associated to the selected algorithm.

Parameters

  [in] | handle | hipsparselt library handle
  [in] | plan | the matrix multiplication plan descriptor.
  [out] | workspaceSize | Workspace size in bytes

Return values

  HIPSPARSE_STATUS_SUCCESS | the operation completed successfully.
  HIPSPARSE_STATUS_INVALID_VALUE | `handle` , `algSelection` or `workspaceSize` is invalid.

## ◆ hipsparseLtMatmulPlanDestroy()

hipsparseStatus_t hipsparseLtMatmulPlanDestroy | ( | const hipsparseLtMatmulPlan_t * | plan | ) |

Destroy a matrix multiplication plan descriptor.

`hipsparseLtMatmulPlanDestroy` releases the resources used by an instance of the matrix multiplication plan. This function is the last call with a specific plan instance.

Parameters

  [in] | plan | the matrix multiplication plan descriptor

Return values

  HIPSPARSE_STATUS_SUCCESS | the operation completed successfully.
  HIPSPARSE_STATUS_INVALID_VALUE | `plan` is invalid.

## ◆ hipsparseLtMatmulPlanInit()

hipsparseStatus_t hipsparseLtMatmulPlanInit | ( | const hipsparseLtHandle_t * | handle,
|  | hipsparseLtMatmulPlan_t * | plan,
|  | const hipsparseLtMatmulDescriptor_t * | matmulDescr,
|  | const hipsparseLtMatmulAlgSelection_t * | algSelection )

Initializes the matrix multiplication plan descriptor.

`hipsparseLtMatmulPlanInit` creates a matrix multiplication plan descriptor. It should be destroyed at the end using hipsparseLtMatmulPlanDestroy.

Parameters

  [in] | handle | hipsparselt library handle
  [out] | plan | the matrix multiplication plan descriptor
  [in] | matmulDescr | the matrix multiplication descriptor
  [in] | algSelection | the algorithm selection descriptor

Return values

  HIPSPARSE_STATUS_SUCCESS | the operation completed successfully.
  HIPSPARSE_STATUS_INVALID_VALUE | `handle` , `plan` , `matmulDescr` , `algSelection` or `workspaceSize` is invalid. HIPSPARSELT_MAT_NUM_BATCHES from matrix A to D are inconisistent

## ◆ hipsparseLtMatmulSearch()

hipsparseStatus_t hipsparseLtMatmulSearch | ( | const hipsparseLtHandle_t * | handle,
|  | hipsparseLtMatmulPlan_t * | plan,
|  | const void * | alpha,
|  | const void * | d_A,
|  | const void * | d_B,
|  | const void * | beta,
|  | const void * | d_C,
|  | void * | d_D,
|  | void * | workspace,
|  | hipStream_t * | streams,
|  | int32_t | numStreams )

Sparse matrix dense matrix multiplication.

`hipsparseLtMatmulSearch` evaluates all available algorithms for the matrix multiplication and automatically updates the plan by selecting the fastest one. The functionality is intended to be used for auto-tuning purposes when the same operation is repeated multiple times over different inputs.

Note
  This function's behavior is the same of hipsparseLtMatmul
  d_C and d_D must be two different memory buffers, otherwise the output will be incorrect.
  This function is NOT asynchronous with respect to streams[0] (blocking call)
  The number of iterations for the evaluation can be set by using hipsparseLtMatmulAlgSetAttribute() with HIPSPARSELT_MATMUL_SEARCH_ITERATIONS.
  The selected algorithm id can be retrieved by using

Parameters

  [in] | handle | hipsparselt library handle
  [in] | plan | Matrix multiplication plan
  [in] | alpha | scalar \(\alpha\). (float)
  [in] | d_A | Pointer to the structured matrix A
  [in] | d_B | Pointer to the dense matrix B
  [in] | beta | scalar \(\beta\). (float)
  [in] | d_C | Pointer to the dense matrix C
  [out] | d_D | Pointer to the dense matrix D
  [in] | workspace | Pointor to the worksapce
  [in] | streams | Pointer to HIP stream array for the computation
  [in] | numStreams | Number of HIP streams in `streams`

Return values

  HIPSPARSE_STATUS_SUCCESS | the operation completed successfully.
  HIPSPARSE_STATUS_NOT_INITIALIZED | `handle` or `plan` is invalid.
  HIPSPARSE_STATUS_INVALID_VALUE | `handle`, `plan` `alpha`, `d_A`, `d_B`, `beta`, `d_C` , `d_D` , `workspace` `streams` or `numStreams` is invalid.
  HIPSPARSE_STATUS_NOT_SUPPORTED | the problme is not supported.