Is this page helpful?

distributed_decompose#

cuquantum.tensornet.experimental.distributed.distributed_decompose(
subscripts,
operand: DistributedTensor,
*,
out_left: BlockCyclic,
out_right: BlockCyclic,
method=None,
options=None,
stream=None,
return_info=False,
)[source]#

Perform QR or SVD decomposition of a distributed tensor based on the expression described by subscripts.

The expression follows the same conventions as cuquantum.tensornet.tensor.decompose(): one input term and two output terms sharing exactly one mode. The operand and both factors are distributed: every process passes the local shard of the operand and receives the local shards of the factors, with each tensor’s placement described by a BlockCyclic distribution.

Parameters:

  • subscripts – The mode labels (subscripts) defining the decomposition, with the same conventions as cuquantum.tensornet.tensor.decompose().

  • operand – The tensor to decompose, as a DistributedTensor with a device-resident local shard.

  • out_left – The placement of the left factor, as a BlockCyclic distribution. The output is always freshly allocated: its local shard is a compact Fortran-order arrangement of the requested distribution, allocated through the operand’s array package. Pre-allocated output buffers are not accepted.

  • out_right – Like out_left, for the right factor. The singular values (SVD only) are likewise always freshly allocated.

  • method – A QRMethod or SVDMethod object (or a dict of the corresponding constructor parameters) selecting the decomposition. Defaults to QR. For SVD, only "gesvdp" is supported. A dict without an algorithm key selects it automatically, so method={'max_extent': 8} works. An SVDMethod instance must set algorithm='gesvdp' because its default is "gesvd". Any other algorithm raises ValueError.

  • options – A DistributedDecompositionOptions object (or a dict); options.handle is required (see the notes below).

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

  • return_info – If true, also return a SVDInfo object describing the decomposition. Supported for SVD only.

Returns:

  • QR returns (left, right) as DistributedTensor objects.

  • SVD returns (left, s, right), where the factors are DistributedTensor objects and s is None if partitioned via partition. When return_info is True, an SVDInfo object is appended to the tuple.

Return type:

Depending on the decomposition method specified in method

Note

When value-based truncation reduces the shared extent, the factors and s carry the realized (reduced) extent; their local arrays are zero-copy views of the capacity-sized allocations (copy them to release the extra memory).

Note

With return_info=True, SVDInfo reports algorithm='gesvdp' and gesvdp_err_sigma=0.0. On the distributed path, gesvdp_err_sigma is not measured and must not be used as a convergence signal; unlike the single-process path, 0.0 does not imply the input was well conditioned.

Note

Prerequisites: initialize nvmath.distributed with an MPI process group, create a cutensornet handle, and configure it with the same MPI communicator via cutensornet.distributed_reset_configuration. The world size and rank of the handle’s communicator are validated against the process group.

Note

Local input shards are currently staged when they are not compact Fortran-order (allocate with empty_local(), inspect with get_local_layout()). Staging performs one device-side copy and leaves the caller’s array unchanged. Outputs use compact Fortran-order layouts.

Note

With value-based SVD truncation (abs_cutoff, rel_cutoff, or discarded_weight_cutoff), the shared mode of each output must be owned by a single rank or explicitly block-cyclic (blockSizes > 0). A near-even slab over more than one rank is rejected.

Note

Validation is rank-local: pass consistent arguments on every process, as an argument rejected on only some ranks leaves the other ranks waiting in a collective. Set options.collective_error_agreement=True to instead ballot across ranks on the Python-side pre-checks, so a rank-divergent failure raises consistently on every rank.

Warning

This API is experimental and subject to future changes.