apply

An implementation of the Successive Randomized Compression (SRC) algorithm.

This module includes the functions used for contraction-compressions of the following types:

1. MPO-MPS randomized contraction-compression.
2. MPO-MPO randomized contraction-compression.

Functions

apply

apply(
    left_tensor: Sequence[NDArray],
    right_tensor: Sequence[NDArray],
    chi_out: int,
    *,
    cutoff: float = 0.0,
    dtype: type = np.float64,
    seed: int | None = None,
    device: str = "cpu"
) -> list[NDArray]

Applies the Successive Randomized Compression (SRC) algorithm.

Tensor trains are plain lists of per-site arrays following the default quimb index ordering; see src_method._tensor_train for the layout. The train type is inferred from the rank of the first site tensor, and dispatch follows:

1. MPO-MPS: left_tensor is an MPO and right_tensor is an MPS. Results in an MPS.
2. MPO-MPO: both left_tensor and right_tensor are MPOs. Results in an MPO.

PARAMETER	DESCRIPTION
left_tensor	The site arrays of the left tensor network (MPO). TYPE: Sequence[NDArray]
right_tensor	The site arrays of the right tensor network (MPO or MPS). TYPE: Sequence[NDArray]
chi_out	The desired maximum bond dimension of the output tensor network. TYPE: int
cutoff	Relative singular-value cutoff for adaptive bond truncation. When positive, bonds are trimmed to their effective rank by discarding singular values below cutoff * sigma_max at each site during the right-to-left sweep. The SVD operates on the small (chi_out, chi_out) R factor from QR, so overhead is minimal. Set to 0.0 (default) to keep all bonds at chi_out. TYPE: float DEFAULT: 0.0
dtype	The data type for the computation. TYPE: type DEFAULT: float64
seed	An optional seed for the random number generator. TYPE: int | None DEFAULT: None
device	"cpu" (default, numpy) or "gpu" (cupy). Requires the optional cupy dependency for GPU execution. TYPE: str DEFAULT: 'cpu'

RETURNS	DESCRIPTION
list[NDArray]	The site arrays of the compressed tensor network (MPS or MPO).

RAISES	DESCRIPTION
TypeError	If the combination of input tensor types is unsupported.
ValueError	If the two trains differ in length, if a sub-three-site train is not exactly two sites, or if device is not recognised.
ImportError	If device="gpu" but cupy is not installed.

Source code in src/src_method/apply.py

def apply(
    left_tensor: Sequence[NDArray],
    right_tensor: Sequence[NDArray],
    chi_out: int,
    *,
    cutoff: float = 0.0,
    dtype: type = np.float64,
    seed: int | None = None,
    device: str = "cpu",
) -> list[NDArray]:
    """Applies the Successive Randomized Compression (SRC) algorithm.

    Tensor trains are plain lists of per-site arrays following the default
    `quimb` index ordering; see `src_method._tensor_train` for the layout.
    The train type is inferred from the rank of the first site tensor, and
    dispatch follows:

      1. MPO-MPS: `left_tensor` is an MPO and `right_tensor` is an MPS. Results in an MPS.
      2. MPO-MPO: both `left_tensor` and `right_tensor` are MPOs. Results in an MPO.

    Args:
        left_tensor: The site arrays of the left tensor network (MPO).
        right_tensor: The site arrays of the right tensor network (MPO or MPS).
        chi_out: The desired maximum bond dimension of the output tensor network.
        cutoff: Relative singular-value cutoff for adaptive bond truncation.
            When positive, bonds are trimmed to their effective rank by
            discarding singular values below ``cutoff * sigma_max`` at each
            site during the right-to-left sweep.  The SVD operates on the
            small ``(chi_out, chi_out)`` R factor from QR, so overhead is
            minimal.  Set to 0.0 (default) to keep all bonds at chi_out.
        dtype: The data type for the computation.
        seed: An optional seed for the random number generator.
        device: ``"cpu"`` (default, numpy) or ``"gpu"`` (cupy).  Requires
            the optional ``cupy`` dependency for GPU execution.

    Returns:
        The site arrays of the compressed tensor network (MPS or MPO).

    Raises:
        TypeError: If the combination of input tensor types is unsupported.
        ValueError: If the two trains differ in length, if a sub-three-site
            train is not exactly two sites, or if ``device`` is not recognised.
        ImportError: If ``device="gpu"`` but cupy is not installed.
    """
    xp = get_xp(device)
    prng = default_rng(seed)

    left_kind = infer_kind(left_tensor)
    right_kind = infer_kind(right_tensor)
    if left_kind != "mpo" or right_kind is None:
        msg = (
            "Unsupported combination of tensor network types: "
            f"{left_kind or 'unknown'} and {right_kind or 'unknown'}; "
            "expected an MPO on the left and an MPS or MPO on the right."
        )
        raise TypeError(msg)

    # Without this the sweep would silently drop the extra sites of the longer train.
    if len(left_tensor) != len(right_tensor):
        msg = (
            "Both tensor trains must have the same number of sites, got "
            f"{len(left_tensor)} and {len(right_tensor)}."
        )
        raise ValueError(msg)

    if len(left_tensor) < MIN_SRC_SITES:
        check_exact_supported(len(left_tensor))
        logger.warning(LOG_WARN_SMALL)
        return exact_apply(left_tensor, right_tensor, chi_out, right_kind)
    if right_kind == "mps":
        return _src_mpo_mps(
            left_tensor, right_tensor, chi_out, prng, xp, cutoff=cutoff, dtype=dtype
        )
    return _src_mpo_mpo(
        left_tensor, right_tensor, chi_out, prng, xp, cutoff=cutoff, dtype=dtype
    )