Skip to content

compress

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

This module includes the functions used for compression of the following types:

  1. MPO randomized compression.
  2. MPS randomized compression.

Functions#

compress #

compress(
    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:

  1. MPS: tensor is an MPS. Results in an MPS.
  2. MPO: tensor is an MPO. Results in an MPO.
PARAMETER DESCRIPTION
tensor

The site arrays of the tensor network to compress (MPS or MPO).

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 input tensor type is unsupported.
ValueError

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/compress.py 
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
def compress(
    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:

      1. MPS: `tensor` is an MPS. Results in an MPS.
      2. MPO: `tensor` is an MPO. Results in an MPO.

    Args:
        tensor: The site arrays of the tensor network to compress (MPS or MPO).
        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 input tensor type is unsupported.
        ValueError: 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)

    kind = infer_kind(tensor)
    if kind is None:
        msg = (
            "Unsupported tensor network layout: expected an MPS or MPO given as a "
            "list of per-site arrays."
        )
        raise TypeError(msg)

    if len(tensor) < MIN_SRC_SITES:
        check_exact_supported(len(tensor))
        logger.warning(LOG_WARN_SMALL)
        return exact_compress(tensor, chi_out, kind)
    if kind == "mps":
        return _src_mps(tensor, chi_out, prng, xp, cutoff=cutoff, dtype=dtype)
    return _src_mpo(tensor, chi_out, prng, xp, cutoff=cutoff, dtype=dtype)