Is this page helpful?

distributed_binary_contraction#

cuquantum.tensornet.experimental.distributed.distributed_binary_contraction(
expr,
a: DistributedTensor,
b: DistributedTensor,
*,
c: DistributedTensor | None = None,
alpha=1.0,
beta=None,
out: BlockCyclic,
options=None,
stream=None,
)[source]#

Evaluate a distributed binary contraction :math:D = \alpha A B + \beta C.

This convenience function plans and executes one contraction. To amortize planning across repeated executions of the same problem, keep a planned DistributedBinaryContraction alive and swap operands with reset_operands().

Currently, non-compact input shards are staged to compact Fortran-order copies. Staging performs one rank-local device copy per incompatible operand and does not modify caller storage. This matches distributed_decompose()’s input staging.

Parameters:

  • expr – The einsum expression (explicit form, exactly two inputs), as for DistributedBinaryContraction.

  • a – The first operand, a DistributedTensor with a known global_shape and a device-resident local shard.

  • b – The second operand, like a.

  • c – Optionally, the addend tensor, like a with the output’s global shape.

  • alpha – Scale factor for the A @ B product.

  • beta – Scale factor for the addend c. Must be set when c is provided, and must be left unset (the default) otherwise.

  • out – The placement of the output, as a BlockCyclic distribution. The output is always freshly allocated in the compact Fortran-order layout through the operands’ array package; pre-allocated output buffers are not accepted.

  • options – A DistributedContractionOptions object (or a dict); options.handle is required.

  • stream – The CUDA stream the operation is ordered on. If not provided, the package’s current stream is used.

Returns:

The freshly allocated output DistributedTensor.

Warning

This API is experimental and subject to future changes.