pub struct OperationDescriptor { /* private fields */ }Implementations§
Source§impl OperationDescriptor
impl OperationDescriptor
Sourcepub fn elementwise_trinary(
ctx: &Context,
lhs: TensorOperand<'_>,
rhs: TensorOperand<'_>,
aux: TensorOperand<'_>,
out: TensorOperand<'_>,
op_ab: Operator,
op_abc: Operator,
compute_descriptor: ComputeDescriptor,
) -> Result<Self>
pub fn elementwise_trinary( ctx: &Context, lhs: TensorOperand<'_>, rhs: TensorOperand<'_>, aux: TensorOperand<'_>, out: TensorOperand<'_>, op_ab: Operator, op_abc: Operator, compute_descriptor: ComputeDescriptor, ) -> Result<Self>
Creates an operation descriptor that encodes an element-wise trinary operation.
The trinary operation has the following general form:
$$ D_{\Pi^C(i_0,i_1,…,i_n)} = \Phi_{ABC}(\Phi_{AB}(\alpha op_A(A_{\Pi^A(i_0,i_1,…,i_n)}), \beta op_B(B_{\Pi^B(i_0,i_1,…,i_n)})), \gamma op_C(C_{\Pi^C(i_0,i_1,…,i_n)})) $$
Where:
- A,B,C,D are multi-mode tensors (of arbitrary data types).
- $\Pi^A, \Pi^B, \Pi^C$ are permutation operators that permute the modes of A, B, and C respectively.
- $op_{A},op_{B},op_{C}$ are unary element-wise operators, such as IDENTITY and CONJUGATE.
- $\Phi_{ABC}, \Phi_{AB}$ are binary element-wise operators, such as ADD, MUL, MAX, and MIN.
Broadcasting can be achieved by omitting that mode from the respective tensor.
Modes may appear in any order. The only restrictions are:
- modes that appear in A or B must also appear in the output tensor; a mode that only appears in the input would be contracted and such an operation would be covered by either
Plan::contractorPlan::reduce. - each mode may appear in each tensor at most once.
Input tensors may be read even if the value of the corresponding scalar is zero.
Examples:
- $D_{a,b,c,d} = A_{b,d,a,c}$
- $D_{a,b,c,d} = 2.2 \cdot A_{b,d,a,c} + 1.3 \cdot B_{c,b,d,a}$
- $D_{a,b,c,d} = 2.2 \cdot A_{b,d,a,c} + 1.3 \cdot B_{c,b,d,a} + C_{a,b,c,d}$
- $D_{a,b,c,d} = min((2.2 \cdot A_{b,d,a,c} + 1.3 \cdot B_{c,b,d,a}), C_{a,b,c,d})$
Call Plan::elementwise_trinary to perform the actual operation.
The returned descriptor frees the cuTENSOR descriptor when dropped.
Supported data-type combinations are:
This may call asynchronous CUDA functions. cuTENSOR treats descriptor creation as thread-safe but not reentrant.
§Errors
Returns an error if the context cannot be bound, tensor modes do not match descriptor ranks, the target architecture is unsupported or not ready, cuTENSOR rejects the operand descriptors, or cuTENSOR returns a null operation descriptor.
Sourcepub fn elementwise_binary(
ctx: &Context,
a: TensorOperand<'_>,
c: TensorOperand<'_>,
d: TensorOperand<'_>,
op_ac: Operator,
compute_descriptor: ComputeDescriptor,
) -> Result<Self>
pub fn elementwise_binary( ctx: &Context, a: TensorOperand<'_>, c: TensorOperand<'_>, d: TensorOperand<'_>, op_ac: Operator, compute_descriptor: ComputeDescriptor, ) -> Result<Self>
Creates an operation descriptor for an element-wise binary operation.
The binary operation has the following general form:
$$ D_{\Pi^C(i_0,i_1,…,i_n)} = \Phi_{AC}(\alpha op_A(A_{\Pi^A(i_0,i_1,…,i_n)}), \gamma op_C(C_{\Pi^C(i_0,i_1,…,i_n)})) $$
Call Plan::elementwise_binary to perform the actual operation.
Supported data-type combinations are:
This may call asynchronous CUDA functions. cuTENSOR treats descriptor creation as thread-safe but not reentrant.
§Errors
Returns an error if the context cannot be bound, tensor modes do not match descriptor ranks, input and output descriptors or mode sets are incompatible, a data type or operator combination is unsupported, cuTENSOR rejects the operands, or cuTENSOR returns a null operation descriptor.
Sourcepub fn permutation(
ctx: &Context,
a: TensorOperand<'_>,
b: TensorOperand<'_>,
compute_descriptor: ComputeDescriptor,
) -> Result<Self>
pub fn permutation( ctx: &Context, a: TensorOperand<'_>, b: TensorOperand<'_>, compute_descriptor: ComputeDescriptor, ) -> Result<Self>
Creates an operation descriptor for a tensor permutation.
The tensor permutation has the following general form:
$$ B_{\Pi^B(i_0,i_1,…,i_n)} = \alpha op_A(A_{\Pi^A(i_0,i_1,…,i_n)}) $$
Consequently, tensor permutation is an out-of-place operation and a specialization of OperationDescriptor::elementwise_binary.
Where:
AandBare multi-mode tensors of arbitrary data types.- $\Pi^A$ and $\Pi^B$ permute the modes of
AandB, respectively. - $op_A$ is a unary element-wise operator such as identity, square, or conjugate.
Broadcasting can be achieved by omitting that mode from the respective tensor.
Modes may appear in any order. The only restrictions are:
- modes that appear in A must also appear in the output tensor.
- each mode may appear in each tensor at most once.
Supported data-type combinations are:
This may call asynchronous CUDA functions. cuTENSOR treats descriptor creation as thread-safe but not reentrant.
§Errors
Returns an error if the context cannot be bound, tensor modes do not match descriptor ranks, a requested output mode is invalid, a data type or operator combination is unsupported, cuTENSOR rejects the operands, or cuTENSOR returns a null operation descriptor.
Sourcepub fn contraction(
ctx: &Context,
a: TensorOperand<'_>,
b: TensorOperand<'_>,
c: TensorOperand<'_>,
d: TensorOperand<'_>,
compute_descriptor: ComputeDescriptor,
) -> Result<Self>
pub fn contraction( ctx: &Context, a: TensorOperand<'_>, b: TensorOperand<'_>, c: TensorOperand<'_>, d: TensorOperand<'_>, compute_descriptor: ComputeDescriptor, ) -> Result<Self>
Creates an operation descriptor for a tensor contraction of the form $D = \alpha \mathcal{A} \mathcal{B} + \beta \mathcal{C}$.
The descriptor represents a 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}}). $$
Use Plan::create to select a kernel, then call Plan::contract to execute the contraction.
The returned descriptor frees the cuTENSOR operation descriptor when dropped.
Supported data-type combinations are:
§Errors
Returns an error if the context cannot be bound, tensor modes do not match descriptor ranks, input and output descriptors or mode sets are incompatible, a data type or operator combination is unsupported, cuTENSOR rejects the operands, or cuTENSOR returns a null operation descriptor.
Sourcepub fn reduction(
ctx: &Context,
a: TensorOperand<'_>,
c: TensorOperand<'_>,
d: TensorOperand<'_>,
op_reduce: Operator,
compute_descriptor: ComputeDescriptor,
) -> Result<Self>
pub fn reduction( ctx: &Context, a: TensorOperand<'_>, c: TensorOperand<'_>, d: TensorOperand<'_>, op_reduce: Operator, compute_descriptor: ComputeDescriptor, ) -> Result<Self>
Creates an operation descriptor for a tensor reduction of the form $D = \alpha \cdot op_reduce(op_A(A)) + \beta \cdot op_C(C)$.
For example, this can reduce an entire tensor to a scalar: C[] = alpha * A[i,j,k].
Can also perform partial reductions; for instance,
C[i,j] = alpha * A[k,j,i].
In this case only elements along the k mode are contracted.
The binary op_reduce operator controls the kind of reduction that is performed.
For instance, setting op_reduce to Operator::Add reduces elements of A via a summation while Operator::Max would find the largest element in A.
Supported data-type combinations are:
§Errors
Returns an error if the context cannot be bound, tensor modes do not match descriptor ranks, input and output descriptors or mode sets are incompatible, a data type or reduction operator combination is unsupported, cuTENSOR rejects the operands, or cuTENSOR returns a null operation descriptor.
Sourcepub fn contraction_trinary(
ctx: &Context,
lhs: TensorOperand<'_>,
rhs: TensorOperand<'_>,
aux: TensorOperand<'_>,
input: TensorOperand<'_>,
output: TensorOperand<'_>,
compute_descriptor: ComputeDescriptor,
) -> Result<Self>
pub fn contraction_trinary( ctx: &Context, lhs: TensorOperand<'_>, rhs: TensorOperand<'_>, aux: TensorOperand<'_>, input: TensorOperand<'_>, output: TensorOperand<'_>, compute_descriptor: ComputeDescriptor, ) -> Result<Self>
Creates an operation descriptor for a tensor contraction of the form $\mathcal{E} = \alpha \mathcal{A} \mathcal{B} \mathcal{C} + \beta \mathcal{D}$.
The descriptor represents a tensor contraction of the form:
$$ \mathcal{E}_{{modes}_\mathcal{E}} \gets \alpha op_\mathcal{A}(\mathcal{A}_{{modes}_\mathcal{A}}) op_\mathcal{B}(\mathcal{B}_{{modes}_\mathcal{B}}) op_\mathcal{C}(\mathcal{C}_{{modes}_\mathcal{C}}) + \beta op_\mathcal{D}(\mathcal{D}_{{modes}_\mathcal{D}}). $$
Use Plan::create to select a kernel, then call Plan::contract_trinary to execute the contraction.
The returned descriptor frees the cuTENSOR operation descriptor when dropped.
Performance improvements are currently especially high for host-resident data, also called out-of-core data, on Grace-based systems.
Supported data-type combinations are:
§Errors
Returns an error if the context cannot be bound, tensor modes do not match descriptor ranks, input and output descriptors or mode sets are incompatible, a data type or operator combination is unsupported, cuTENSOR rejects the operands, or cuTENSOR returns a null operation descriptor.
Sourcepub fn block_sparse_contraction(
ctx: &Context,
a: BlockSparseTensorOperand<'_>,
b: BlockSparseTensorOperand<'_>,
c: BlockSparseTensorOperand<'_>,
d: BlockSparseTensorOperand<'_>,
compute_descriptor: ComputeDescriptor,
) -> Result<Self>
pub fn block_sparse_contraction( ctx: &Context, a: BlockSparseTensorOperand<'_>, b: BlockSparseTensorOperand<'_>, c: BlockSparseTensorOperand<'_>, d: BlockSparseTensorOperand<'_>, compute_descriptor: ComputeDescriptor, ) -> Result<Self>
Creates an operation descriptor for a block-sparse tensor contraction of the form $D = \alpha \mathcal{A} \mathcal{B} + \beta \mathcal{C}$.
The descriptor represents 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 BlockSparseTensorDescriptor::create 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 are 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 DataType::ComplexF64, DataType::ComplexF32, DataType::F64, and DataType::F32.
The compute type must match as well; currently supported combinations are:
For every mode, the segmentation of that mode must be identical in all tensors that it occurs in.
For example, if mode i of tensor A matches mode j of tensor B, then the section count for mode i in A must match the section count for mode j in 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 must have the same number of block-rows, and each block-row of C must contain the same number of rows as the corresponding block-row of A.
- Mode ‘n’: C and B must have the same number of block-columns of matching size.
- Mode ‘k’: A must have the same number of block-columns as B has block-rows, and each block-column of A must contain the same number of columns as the number of rows in the corresponding block-row of B.
input and output must use identical descriptors: the same opaque pointer must be passed, and the layouts of the input and output tensors must be identical.
See sys::cutensorCreatePlan to create the plan, Plan::estimate_workspace_size to compute the required workspace, and finally Plan::block_sparse_contract to perform the actual contraction.
The returned descriptor frees the cuTENSOR operation descriptor when dropped.
§Errors
Returns an error if the context cannot be bound, block-sparse tensor modes do not match descriptor ranks, input and output descriptors or mode sets are incompatible, section sizes are invalid, a data type or operator combination is unsupported, cuTENSOR rejects the operands, or cuTENSOR returns a null operation descriptor.
pub fn tag(&self) -> Result<i32>
pub fn set_tag(&mut self, tag: i32) -> Result<()>
pub fn scalar_type(&self) -> Result<DataType>
pub fn set_scalar_type(&mut self, data_type: DataType) -> Result<()>
pub fn padding_left(&self) -> Result<Vec<u32>>
pub fn set_padding_left(&mut self, padding: &[u32]) -> Result<()>
pub fn padding_right(&self) -> Result<Vec<u32>>
pub fn set_padding_right(&mut self, padding: &[u32]) -> Result<()>
pub fn set_padding_value<T: DataTypeLike>(&mut self, value: T) -> Result<()>
pub fn flops(&self) -> Result<f32>
pub fn moved_bytes(&self) -> Result<f32>
pub const fn as_raw(&self) -> cutensorOperationDescriptor_t
Sourcepub fn into_raw(self) -> cutensorOperationDescriptor_t
pub fn into_raw(self) -> cutensorOperationDescriptor_t
Consumes the descriptor and returns the raw cuTENSOR operation descriptor handle without destroying it.
The caller becomes responsible for eventually destroying the returned handle with cuTENSOR.