Skip to main content

cutensorCreateBlockSparseContraction

singe_cutensor_sys

Function cutensorCreateBlockSparseContraction 

Source 
pub unsafe extern "C" fn cutensorCreateBlockSparseContraction(
    handle: cutensorHandle_t,
    desc: *mut cutensorOperationDescriptor_t,
    descA: cutensorBlockSparseTensorDescriptor_t,
    modeA: *const i32,
    opA: cutensorOperator_t,
    descB: cutensorBlockSparseTensorDescriptor_t,
    modeB: *const i32,
    opB: cutensorOperator_t,
    descC: cutensorBlockSparseTensorDescriptor_t,
    modeC: *const i32,
    opC: cutensorOperator_t,
    descD: cutensorBlockSparseTensorDescriptor_t,
    modeD: *const i32,
    descCompute: cutensorComputeDescriptor_t,
) -> cutensorStatus_t
Expand description

This function allocates a cutensorOperationDescriptor_t object that encodes a block-sparse tensor contraction of the form $D = \alpha \mathcal{A} \mathcal{B} + \beta \mathcal{C}$.

Allocates data for desc to be used to perform a block-sparse tensor contraction of the form:

$$ \mathcal{D}{{modes}\mathcal{D}} \gets \alpha op_\mathcal{A}(\mathcal{A}{{modes}\mathcal{A}}) op_\mathcal{B}(B_{{modes}\mathcal{B}}) + \beta op\mathcal{C}(\mathcal{C}{{modes}\mathcal{C}}). $$ Only the predefined non-zero blocks of $\mathcal{D}$ that were specified in cutensorCreateBlockSparseTensorDescriptor() are actually computed. The other blocks are omitted, even if the true result of the contraction would be non-zero. Conversely, if a predefined non-zero block of $\mathcal{D}$ is present, but the result of the contraction is zero for this block, explicit zeros will be stored.

Currently, the data-types for the tensors A, B, C, and D, as well as the scalars $\alpha$ and $\beta$ must all be identical, and the only supported types are cudaDataType_t::CUDA_C_64F, cudaDataType_t::CUDA_C_32F, cudaDataType_t::CUDA_R_64F, and cudaDataType_t::CUDA_R_32F. The compute-type needs to match as well, that is, we currently only support:

For every mode, the segmentation of that mode must be identical in all tensors that it occurs in. For example, if modeA[i] = modeB[j] for some i and j, then numSectionsPerMode[i] of tensor A must have the same value as numSectionsPerMode[j] of tensor B, and the corresponding section extents must be identical.

For example, let A, B, and C be block matrices and consider the ordinary matrix-matrix product $C_{mn}=A_{mk}B_{kn}$. Then:

  • Mode ‘m’: C and A need to have the same number of block-rows, and each block-row of C needs to contain the same number of rows as the corresponding block-row of A.
  • Mode ‘n’: C and B need to have the same number of block-columns of matching size
  • Mode ‘k’: A needs to have the same number of block-columns as B has block-rows, and each block-column of A needs to consist of the same number of columns as the number of rows in the corresponding block-row of B.

At the moment, descC and descD must be identical, i.e., the same opaque pointer needs to be passed and the layouts of the C and the D tensors need to be identical.

See cutensorCreatePlan to create the plan, cutensorEstimateWorkspaceSize to compute the required workspace, and finally cutensorBlockSparseContract to perform the actual contraction.

The user is responsible for calling cutensorDestroyOperationDescriptor to free the resources associated with the descriptor.

§Parameters

  • handle: Opaque handle holding cuTENSOR’s library context.
  • desc: This opaque struct gets allocated and filled with the information that encodes the tensor contraction operation.
  • descA: The descriptor that holds the information about the data type, modes, sections, section extents, strides, and non-zero blocks of A.
  • modeA: Array with ‘nmodeA’ entries that represent the modes of A. Sections, i.e., block-sizes, must match among the involved block-sparse tensors.
  • opA: Unary operator that will be applied to each element of A before it is further processed. The original data of this tensor remains unchanged. Currently, only cutensorOperator_t::CUTENSOR_OP_IDENTITY is supported.
  • descB: The descriptor that holds information about the the data type, modes, sections, section extents, strides, and non-zero blocks of B.
  • modeB: Array with ‘nmodeB’ entries that represent the modes of B. Sections, i.e., block-sizes, must match among the involved block-sparse tensors.
  • opB: Unary operator that will be applied to each element of B before it is further processed. The original data of this tensor remains unchanged. Currently, only cutensorOperator_t::CUTENSOR_OP_IDENTITY is supported.
  • descC: The descriptor that holds information about the data type, modes, sections, section extents, strides, and non-zero blocks of C. Note that the block-sparsity pattern of C (the nonZeroCoordinates[] array used to create the decriptor) of C must be identical to that of D; and it is this block-sparsity pattern that determines which parts of the results are computed; no fill-in is allocated or computed.
  • modeC: Array with ‘nmodeC’ entries that represent the modes of C. Sections, i.e., block-sizes, must match among the involved block-sparse tensors.
  • opC: Unary operator that will be applied to each element of C before it is further processed. The original data of this tensor remains unchanged. Currently, only cutensorOperator_t::CUTENSOR_OP_IDENTITY is supported.
  • descD: For now, this must be the same opaque pointer as descC, and the layouts of C and D must be identical.
  • modeD: Array with ‘nmodeD’ entries that represent the modes of D (must be identical to modeC for now).

§Return value