src

Successive Randomized Compression of a stack of tensor trains.

A stack T_1 . T_2 . ... . T_m is an ordered sequence of trains contracted along their physical legs and compressed in a single SRC sweep. apply and compress are the two-train and one-train special cases.

funcsrc

(*trains, chi_out, cutoff=0.0, oversample=1.0, dtype=None, seed=None, device='cpu', resources=None, optimize=DEFAULT_OPTIMIZE) -> list[np.ndarray]

Contract a stack of tensor trains and compress the result with SRC.

The stack src(T_1, T_2, ..., T_m) is the product T_1 T_2 ... T_m in mathematical order: T_m acts first. Trains are plain lists of per-site arrays in the default quimb layout, their kind inferred from the rank of the first site tensor. Each contraction joins the d leg of a train with the u (or physical) leg of the next. Accepted stacks:

one MPS or one MPO: plain compression;
A_1, ..., A_k: an MPO product, giving an MPO;
A_1, ..., A_k, psi: an MPO product applied to a ket, giving an MPS;
phi, A_1, ..., A_k: a bra times an MPO product, giving an MPS on the d leg of A_k.

A leading MPS is contracted without conjugation, as the row vector phi^T A_1 ... A_k. For the physical bra <psi| A_1 ... A_k, pass [t.conj() for t in psi]; the result then pairs with a ket by plain contraction.

The per-site cost grows with the sketch size squared times the product of the layer bond dimensions, so one sweep pays off for shallow stacks of thin layers (for example two or three Trotter layers). Apply anything else pairwise.

Raises

TypeError: If chi_out is not an integer, if a train has an unrecognised layout or an MPS sits anywhere other than at one end of the stack, or if optimize is neither a name nor a PathOptimizer.
ValueError: If chi_out is not positive, if cutoff is not in [0.0, 1.0), if oversample is not finite and at least 1.0, if a train is not open-boundary, if the stack is empty, if the trains differ in length or in the physical dimensions they join, if a sub-three-site stack is not exactly two sites, if optimize names no opt_einsum path optimizer, or if device is not recognised.
ImportError: If device="gpu" but cupy is not installed.

paramtrainsSequence[Site]

The site arrays of each train, in mathematical order. A site may also be any array-like with shape, dtype, ndim and np.asarray support (SiteLike), such as np.memmap or a zarr or HDF5 dataset; it is then read only when the sweep reaches it.

paramchi_outint | np.integer

The desired maximum bond dimension of the output train.

paramcutofffloat

= 0.0

Relative singular-value cutoff for adaptive bond truncation. Discards singular values below cutoff * sigma_max: on the sketch's QR factor during the right-to-left sweep or, when oversampling, in the final left-to-right SVD pass. Set to 0.0 (default) to disable cutoff trimming. Ignored for two-site stacks, which are contracted and truncated to chi_out exactly.

paramoversamplefloat | None

= 1.0

Multiplicative sketch-size factor, finite and at least 1.0. The sketch size is ceil(oversample * chi_out); None uses the paper's max(ceil(1.5 * chi_out), chi_out + 10). An oversampled sweep is followed by an exact SVD truncation to chi_out, which improves accuracy at a higher cost. Defaults to 1.0, no oversampling. Ignored for two-site stacks.

paramdtypeDTypeLike | None

= None

Data type of the random sketches. Defaults to the promoted floating dtype of the inputs, so single precision stays single and complex inputs get complex Ginibre sketches. An explicit dtype overrides this and can promote the result.

paramseedint | None

= None

An optional seed for the random number generator.

paramdevicestr

= 'cpu'

"cpu" (default, numpy) or "gpu" (cupy). Requires the optional cupy dependency for GPU execution.

paramresourcesResources | None

= None

Memory budgets and scratch space for the sweep (see Resources); every budget left unset is detected. Ignored for two-site stacks.

paramoptimizestr | PathOptimizer

= DEFAULT_OPTIMIZE

The opt_einsum path optimizer of the sweep's contractions: any name opt_einsum knows ("dp", "auto", "greedy", ... or one added with opt_einsum.paths.register_path_fn) or an opt_einsum.paths.PathOptimizer instance. The memory plan sizes batches for the same paths. Defaults to "dp", the cheapest paths. Ignored for two-site stacks.

Returns

list

The site arrays of the compressed train (MPS or MPO), as numpy arrays (host-side, whatever the device), in right-canonical form, or left-canonical form when oversampling (three sites or more).