quimb.tensor.tn1d.compress¶

Generic methods for compressing 1D-like tensor networks, where the tensor network can locally have arbitrary structure and outer indices.

[x] the direct method
[x] the density matrix method
[x] successive randomized compression (SRC) method
[x] src-oversampled
[x] successive deterministic compression (SDC) method
[x] sdc-oversampled
[x] successive deterministic compression with randomized SVDs (SDCR) method
[x] sdcr-oversampled
[x] the zip-up method
[x] the zip-up first / oversampled method
[x] the 1-site variational fit method, including sums of tensor networks
[x] the 2-site variational fit method, including sums of tensor networks

Attributes¶

`tensor_network_1d_compress_fit_zipup`
`tensor_network_1d_compress_fit_projector`
`_TN1D_COMPRESS_METHODS`
`_TN1D_COMPRESS_DEFAULT_CUTOFFS`

Functions¶

`enforce_1d_like`(tn[, site_tags, fix_bonds, inplace])	Check that `tn` is 1D-like with OBC, i.e. 1) that each tensor has
`possibly_permute_`(tn, permute_arrays)
`tensor_network_1d_compress_direct`(tn[, max_bond, ...])	Compress a 1D-like tensor network using the 'direct' or 'naive' method,
`_form_final_tn_from_tensor_sequence`(...)	Form the final, compressed tensor network given the the original target
`_phase_dm_operator`(rho, left_inds, right_inds)	Apply fermionic signs before decomposing `rho`.
`tensor_network_1d_compress_dm`(tn[, max_bond, cutoff, ...])	Compress any 1D-like tensor network using the 'density matrix' method
`tensor_network_1d_compress_zipup`(tn[, max_bond, ...])	Compress a 1D-like tensor network using the 'zip-up' algorithm due to
`_do_direct_sweep`(tn, site_tags, max_bond, cutoff, ...)
`tensor_network_1d_compress_zipup_oversample`(tn[, ...])	Compress this 1D-like tensor network using the 'zip-up first' algorithm,
`_conj_project`(→ quimb.tensor.tensor_core.Tensor)	Conjugate the isometry `tq`, such that the pair resolves to the
`_do_sweep_compress_from_low_rank_left_envs`(...)	Form a compressed MPS for any method that produces a sequence of
`_src_get_local_noise_tensors`(tn, rng, noise_mode, ...)
`tensor_network_1d_compress_sdc`(tn, max_bond[, cutoff, ...])	Compress any 1D-like tensor network using 'Successive Deterministic
`tensor_network_1d_compress_sdc_oversample`(tn, max_bond)	Compress this 1D-like tensor network using the 'sdc-oversample'
`tensor_network_1d_compress_sdcr`(tn, max_bond[, ...])	Compress any 1D-like tensor network using 'Successive Deterministic
`tensor_network_1d_compress_sdcr_oversample`(tn, max_bond)	Compress this 1D-like tensor network using the 'sdcr-oversample'
`tensor_network_1d_compress_src`(tn, max_bond[, cutoff, ...])	Compress any 1D-like tensor network using 'Successive Randomized
`tensor_network_1d_compress_src_oversample`(tn, max_bond)	Compress this 1D-like tensor network using the 'src first' algorithm,
`tensor_network_1d_compress_srcmps`(tn, max_bond[, ...])	Compress any 1D-like tensor network using 'Successive Randomized
`tensor_network_1d_compress_srcmps_oversample`(tn, max_bond)	Compress this 1D-like tensor network using the 'srcmps-oversample'
`_conjugate_fit_update`(→ None)	Conjugate a local fit update in place.
`_tn1d_fit_sum_sweep_1site`(tn_fit, tn_overlaps, site_tags)	Core sweep of the 1-site 1D fit algorithm.
`_tn1d_fit_sum_sweep_2site`(tn_fit, tn_overlaps, site_tags)	Core sweep of the 2-site 1D fit algorithm.
`tensor_network_1d_compress_fit`(tns[, max_bond, ...])	Compress any 1D-like (can have multiple tensors per site) tensor network
`tensor_network_1d_compress_fit_guess`(tn, guess[, ...])	Compress any 1D-like (can have multiple tensors per site) tensor network
`tensor_network_1d_compress_fit_oversample`(tn[, ...])	Compress this 1D-like tensor network using the 'fit-oversample'
`tensor_network_1d_compress`(...)	Compress a 1D-like tensor network, or sequence of such networks
`mps_gate_with_mpo_lazy`(mps, mpo[, inplace])	Apply an MPO to an MPS lazily, i.e. nothing is contracted, but the new
`mps_gate_with_mpo_direct`(mps, mpo[, max_bond, cutoff, ...])	Apply an MPO to an MPS using the boundary compression method, that is,
`mps_gate_with_mpo_dm`(mps, mpo[, max_bond, cutoff, inplace])	Gate this MPS with an MPO, using the density matrix compression method.
`mps_gate_with_mpo_zipup`(mps, mpo[, max_bond, cutoff, ...])	Apply an MPO to an MPS using the 'zip-up' algorithm due to
`mps_gate_with_mpo_zipup_first`(mps, mpo[, max_bond, ...])	Apply an MPO to an MPS by first using the zip-up method with a larger
`mps_gate_with_mpo_fit`(mps, mpo, max_bond, **kwargs)	Gate an MPS with an MPO using the variational fitting or DMRG-style
`mps_gate_with_mpo_autofit`(self, mpo, max_bond[, ...])	Fit a MPS to a MPO applied to an MPS using geometry generic versions
`mps_gate_with_mpo_projector`(self, mpo, max_bond[, ...])	Apply an MPO to an MPS using local projectors, in the style of CTMRG

Module Contents¶

quimb.tensor.tn1d.compress.enforce_1d_like(tn, site_tags=None, fix_bonds=True, inplace=False)[source]¶

Check that tn is 1D-like with OBC, i.e. 1) that each tensor has exactly one of the given site_tags. If not, raise a ValueError. 2) That there are no hyper indices. And 3) that there are only bonds within sites or between nearest neighbor sites. This issue can be optionally automatically fixed by inserting a string of identity tensors.

Parameters:

tn (TensorNetwork) – The tensor network to check.
site_tags (sequence of str, optional) – The tags to use to group and order the tensors from tn. If not given, uses tn.site_tags.
fix_bonds (bool, optional) – Whether to fix the bond structure by inserting identity tensors.
inplace (bool, optional) – Whether to perform the fix inplace or not.

Raises:

ValueError – If the tensor network is not 1D-like.

quimb.tensor.tn1d.compress.possibly_permute_(tn: quimb.tensor.tensor_core.TensorNetwork, permute_arrays: bool | str)[source]¶

quimb.tensor.tn1d.compress.tensor_network_1d_compress_direct(tn: quimb.tensor.tensor_core.TensorNetwork, max_bond=None, cutoff=1e-10, site_tags=None, normalize=False, canonize=True, cutoff_mode='rsum2', permute_arrays=True, optimize='auto-hq', sweep_reverse=False, equalize_norms=False, contract_opts=None, canonize_opts=None, compress_opts=None, inplace=False, **kwargs)[source]¶

Compress a 1D-like tensor network using the ‘direct’ or ‘naive’ method, that is, explicitly contracting site-wise to form a MPS-like TN, canonicalizing in one direction, then compressing in the other. This has the same scaling as the density matrix (dm) method, but a larger prefactor. It can still be faster for small bond dimensions however, and is potentially higher precision since it works in the space of singular values directly rather than singular values squared. It is not quite optimal in terms of error due to the compounding errors of the SVDs.

Parameters:

tn (TensorNetwork) – The tensor network to compress. Every tensor should have exactly one of the site tags. Each site can have multiple tensors and output indices.
max_bond (int) – The maximum bond dimension to compress to.
cutoff (float, optional) – A dynamic threshold for discarding singular values when compressing.
site_tags (sequence of str or tag groups, optional) – Tags that identify and order sites. Defaults to tn.site_tags. Each item can group tags as described by parse_site_tag_groups(). The output has one tensor per item.
normalize (bool, optional) – Whether to normalize the final tensor network, making use of the fact that the output tensor network is in right canonical form.
canonize (bool, optional) – Whether to canonicalize the network in one direction before compressing in the other.
cutoff_mode ({"rsum2", "rel", ...}, optional) – The mode to use when truncating the singular values of the decomposed tensors. See tensor_split().
permute_arrays (bool or str, optional) – Whether to permute the array indices of the final tensor network into canonical order. If True will use the default order, otherwise if a string this specifies a custom order.
optimize (str, optional) – The contraction path optimizer to use.
sweep_reverse (bool, optional) – Whether to sweep in the reverse direction, resulting in a left canonical form instead of right canonical.
equalize_norms (bool, optional) – Whether to renormalize the tensors during the compression procedure. If True the gathered exponent will be redistributed equally among the tensors. If a float, all tensors will be renormalized to this value, and the gathered exponent is tracked in tn.exponent of the returned tensor network.
inplace (bool, optional) – Whether to perform the compression inplace or not.
contract_opts (dict, optional) – Supplied to tensor_contract(). Values set here take precedence over any defaults.
canonize_opts (dict, optional) – Supplied to canonize_between() when canonizing between sites. Values set here take precedence over any defaults.
compress_opts (dict, optional) – Supplied to compress_between() when compressing between sites. Values set here take precedence over any defaults.
kwargs – Extra keyword arguments are combined into compress_opts, though existing items in compress_opts take precedence over kwargs.

Returns:

The compressed tensor network, with canonical center at site_tags[0] (‘right canonical’ form) or site_tags[-1] (‘left canonical’ form) if sweep_reverse.

Return type:

TensorNetwork

quimb.tensor.tn1d.compress._form_final_tn_from_tensor_sequence(tn: quimb.tensor.tensor_core.TensorNetwork, ts: list[quimb.tensor.tensor_core.Tensor], normalize: bool, sweep_reverse: bool, permute_arrays: bool | str, equalize_norms: bool | float, exponent=0.0, inplace=False) → quimb.tensor.tensor_core.TensorNetwork[source]¶

Form the final, compressed tensor network given the the original target (uncompressed) tensor network and the new sequence of tensors, e.g. sequence of unitaries from the dm method.

Parameters:

tn (TensorNetwork) – The original target tensor network.
ts (list of Tensor) – The sequence of tensors describing the compressed tensor network, assumed to be in ‘right canonical’ form.
normalize (bool) – Whether to normalize the final tensor network, making use of the fact that the output tensor network is in right canonical form.
sweep_reverse (bool) – Whether to reverse the order the tensors are inserted, e.g. if site_tags have been reversed, purely for cosmetic ordering of the resulting tensor_map.
permute_arrays (bool or str) – Whether to permute the array indices of the final tensor network into canonical order. If True will use the default order, if any (e.g. MatrixProductState), otherwise if a string this specifies a custom order.
equalize_norms (bool or float) – Whether to equalize the norms of the tensors after compression. If an explicit value is given, then the norms will be set to that value, and the overall scaling factor will be accumulated into .exponent. If True, whatever current .exponent will be distributed equally among the tensors.
exponent (float) – An exponent value to add to the final tensor network’s existing exponent, e.g. generated during the compression procedure.
inplace (bool) – Whether to perform the compression inplace or not.

quimb.tensor.tn1d.compress._phase_dm_operator(rho: quimb.tensor.tensor_core.Tensor, left_inds, right_inds)[source]¶

Apply fermionic signs before decomposing rho.

If the first left index is not dual, flip all right indices. This makes the kept eigenspace match a direct SVD.

quimb.tensor.tn1d.compress.tensor_network_1d_compress_dm(tn: quimb.tensor.tensor_core.TensorNetwork, max_bond=None, cutoff=1e-10, site_tags=None, normalize=False, cutoff_mode='rsum1', permute_arrays=True, optimize='auto-hq', sweep_reverse=False, canonize=True, equalize_norms=False, contract_opts=None, compress_opts=None, inplace=False, **kwargs)[source]¶

Compress any 1D-like tensor network using the ‘density matrix’ method (https://tensornetwork.org/mps/algorithms/denmat_mpo_mps/).

While this has the same scaling as the direct method, in practice it can often be faster, especially at large bond dimensions. Potentially there are some situations where the direct method is more stable with regard to precision, since the density matrix method works in the ‘squared’ picture.

Parameters:

tn (TensorNetwork) – The tensor network to compress. Every tensor should have exactly one of the site tags. Each site can have multiple tensors and output indices.
max_bond (int) – The maximum bond dimension to compress to.
cutoff (float, optional) – The truncation error to use when compressing the double layer tensor network.
site_tags (sequence of str or tag groups, optional) – Tags that identify and order sites. Defaults to tn.site_tags. Each item can group tags as described by parse_site_tag_groups(). The output has one tensor per item.
normalize (bool, optional) – Whether to normalize the final tensor network, making use of the fact that the output tensor network is in right canonical form.
cutoff_mode ({"rsum1", "rel", ...}, optional) – The mode to use when truncating the singular values of the decomposed tensors. See tensor_split(). Note for the density matrix method the default ‘rsum1’ mode acts like ‘rsum2’ for the direct method due to truncating in the squared space.
permute_arrays (bool or str, optional) – Whether to permute the array indices of the final tensor network into canonical order. If True will use the default order, otherwise if a string this specifies a custom order.
optimize (str, optional) – The contraction path optimizer to use.
sweep_reverse (bool, optional) – Whether to sweep in the reverse direction, resulting in a left canonical form instead of right canonical.
canonize (bool, optional) – Dummy argument to match the signature of other compression methods.
equalize_norms (bool or float, optional) – Whether to equalize the norms of the tensors after compression. If an explicit value is given, then the norms will be set to that value, and the overall scaling factor will be accumulated into .exponent.
inplace (bool, optional) – Whether to perform the compression inplace or not.
contract_opts (dict, optional) – Supplied to tensor_contract(). Values set here take precedence over any defaults.
compress_opts (dict, optional) – Supplied to tensor_split(). Values set here take precedence over any defaults.
kwargs – Extra keyword arguments are combined into compress_opts, though existing items in compress_opts take precedence over kwargs.

Returns:

The compressed tensor network, with canonical center at site_tags[0] (‘right canonical’ form) or site_tags[-1] (‘left canonical’ form) if sweep_reverse.

Return type:

TensorNetwork

quimb.tensor.tn1d.compress.tensor_network_1d_compress_zipup(tn: quimb.tensor.tensor_core.TensorNetwork, max_bond=None, cutoff=1e-10, site_tags=None, canonize=True, normalize=False, cutoff_mode='rel', permute_arrays=True, optimize='auto-hq', sweep_reverse=False, equalize_norms=False, contract_opts=None, canonize_opts=None, compress_opts=None, inplace=False, **kwargs)[source]¶

Compress a 1D-like tensor network using the ‘zip-up’ algorithm due to ‘Minimally Entangled Typical Thermal State Algorithms’, E.M. Stoudenmire & Steven R. White (https://arxiv.org/abs/1002.1305). The returned tensor network will have one tensor per site, in the order given by site_tags, with canonical center at site_tags[0] (‘right’ canonical form).

The zipup algorithm scales better than the direct and density matrix methods when multiple tensors are present at each site (such as MPO-MPS multiplication), but is less accurate due to the compressions taking place in an only pseudo-canonical gauge. It generally also only makes sense in the fixed bond dimension case, as opposed to relying on a specific cutoff only.

Parameters:

tn (TensorNetwork) – The tensor network to compress. Every tensor should have exactly one of the site tags. Each site can have multiple tensors and output indices.
max_bond (int) – The maximum bond dimension to compress to.
cutoff (float, optional) – A dynamic threshold for discarding singular values when compressing.
site_tags (sequence of str or tag groups, optional) – Tags that identify and order sites. Defaults to tn.site_tags. Each item can group tags as described by parse_site_tag_groups(). The output has one tensor per item.
canonize (bool, optional) – Whether to pseudo canonicalize the initial tensor network.
normalize (bool, optional) – Whether to normalize the final tensor network, making use of the fact that the output tensor network is in right canonical form.
cutoff_mode ({"rel", "rsum2", ...}, optional) – The mode to use when truncating the singular values of the decomposed tensors. See tensor_split().
permute_arrays (bool or str, optional) – Whether to permute the array indices of the final tensor network into canonical order. If True will use the default order, otherwise if a string this specifies a custom order.
optimize (str, optional) – The contraction path optimizer to use.
sweep_reverse (bool, optional) – Whether to sweep in the reverse direction, resulting in a left canonical form instead of right canonical.
equalize_norms (bool or float, optional) – Whether to equalize the norms of the tensors after compression. If an explicit value is given, then the norms will be set to that value, and the overall scaling factor will be accumulated into .exponent.
contract_opts (dict, optional) – Supplied to tensor_contract(). Values set here take precedence over any defaults.
canonize_opts (dict, optional) – Supplied to canonize_around_() when pseudo-canonicalizing. Values set here take precedence over defaults.
inplace (bool, optional) – Whether to perform the compression inplace or not.
compress_opts (dict, optional) – Supplied to tensor_split(). Values set here take precedence over defaults.
kwargs – Extra keyword arguments are combined into compress_opts, though existing items in compress_opts take precedence over kwargs.

Returns:

The compressed tensor network, with canonical center at site_tags[0] (‘right canonical’ form) or site_tags[-1] (‘left canonical’ form) if sweep_reverse.

Return type:

TensorNetwork

quimb.tensor.tn1d.compress._do_direct_sweep(tn: quimb.tensor.tensor_core.TensorNetwork, site_tags, max_bond, cutoff, cutoff_mode, equalize_norms, normalize, permute_arrays, compress_opts=None, **kwargs)[source]¶

quimb.tensor.tn1d.compress.tensor_network_1d_compress_zipup_oversample(tn: quimb.tensor.tensor_core.TensorNetwork, max_bond=None, max_bond_oversample=None, cutoff=1e-10, cutoff_oversample='auto', site_tags=None, canonize=True, normalize=False, cutoff_mode='rsum2', cutoff_mode_oversample='rel', permute_arrays=True, optimize='auto-hq', sweep_reverse=False, equalize_norms=False, contract_opts=None, canonize_opts=None, compress_opts=None, compress_opts_final=None, inplace=False, **kwargs)[source]¶

Compress this 1D-like tensor network using the ‘zip-up first’ algorithm, that is, first compressing the tensor network to a larger bond dimension using the ‘zip-up’ algorithm, then compressing to the desired bond dimension using a direct sweep.

Depending on the value of max_bond and max_bond_oversample, this can be scale better than the direct and density matrix methods, but reach close to the same accuracy. As with the ‘zip-up’ method, there is no advantage unless there are multiple tensors per site, and it generally only makes sense in the fixed bond dimension case, as opposed to relying on a specific cutoff only.

Parameters:

tn (TensorNetwork) – The tensor network to compress. Every tensor should have exactly one of the site tags. Each site can have multiple tensors and output indices.
max_bond (int) – The final maximum bond dimension to compress to.
max_bond_oversample (int, optional) – The intermediate maximum bond dimension to compress to using the ‘zip-up’ algorithm. If not given and max_bond is, this is set as twice the target bond dimension, 2 * max_bond.
cutoff (float, optional) – A dynamic threshold for discarding singular values when compressing.
cutoff_oversample (float or "auto", optional) – A dynamic threshold for discarding singular values when compressing to the intermediate bond dimension using the ‘zip-up’ algorithm. With "auto", use 0.0 for randomized SVD and 1e-10 for exact decompositions, independently of the final sweep’s cutoff.
site_tags (sequence of str or tag groups, optional) – Tags that identify and order sites. Defaults to tn.site_tags. Each item can group tags as described by parse_site_tag_groups(). The output has one tensor per item.
canonize (bool, optional) – Whether to pseudo canonicalize the initial tensor network.
normalize (bool, optional) – Whether to normalize the final tensor network, making use of the fact that the output tensor network is in right canonical form.
cutoff_mode ({"rsum2", "rel", ...}, optional) – The mode used in the final canonical sweep. See tensor_split().
cutoff_mode_oversample ({"rel", "rsum2", ...}, optional) – The mode used in the intermediate pseudo-canonical zipup step, independently of the final sweep. Defaults to "rel".
permute_arrays (bool or str, optional) – Whether to permute the array indices of the final tensor network into canonical order. If True will use the default order, otherwise if a string this specifies a custom order.
optimize (str, optional) – The contraction path optimizer to use.
sweep_reverse (bool, optional) – Whether to sweep in the reverse direction, resulting in a left canonical form instead of right canonical.
equalize_norms (bool or float, optional) – Whether to equalize the norms of the tensors after compression. If an explicit value is given, then the norms will be set to that value, and the overall scaling factor will be accumulated into .exponent.
contract_opts (dict, optional) – Supplied to tensor_contract(). Values set here take precedence over any defaults.
canonize_opts (dict, optional) – Supplied to tensor_network_1d_compress_zipup() when pseudo-canonicalizing in the oversampling step.
compress_opts (dict, optional) – Supplied to tensor_split() in the intermediate zipup step only. Values set here take precedence over defaults.
compress_opts_final (dict, optional) – Options for the final direct sweep, independently of compress_opts. Defaults to exact SVD. Values set here override the final sweep’s max_bond, cutoff, and cutoff_mode.
inplace (bool, optional) – Whether to perform the compression inplace or not.
kwargs – Extra keyword arguments are combined into compress_opts, though existing items in compress_opts take precedence over kwargs.

Returns:

The compressed tensor network, with canonical center at site_tags[0] (‘right canonical’ form) or site_tags[-1] (‘left canonical’ form) if sweep_reverse.

Return type:

TensorNetwork

quimb.tensor.tn1d.compress._conj_project(tq: quimb.tensor.tensor_core.Tensor, bond_ind: str) → quimb.tensor.tensor_core.Tensor[source]¶

Conjugate the isometry tq, such that the pair resolves to the identity when inserted back into a tensor network on bond_ind.

Fermionic data needs possible phases on the contracted indices.

Parameters:

tq (Tensor) – The isometry, bond_ind being its only index not contracted back into the network.
bond_ind (str) – The new bond index produced when tq was split off.

Return type:

Tensor

quimb.tensor.tn1d.compress._do_sweep_compress_from_low_rank_left_envs(tn: quimb.tensor.tensor_core.TensorNetwork, local_tns: list[quimb.tensor.tensor_core.TensorNetwork], left_envs: dict[int, quimb.tensor.tensor_core.Tensor], left_env_inds: dict[int, list[str]], contract_opts: dict, project_opts: dict, equalize_norms: bool | float, normalize: bool, sweep_reverse: bool, permute_arrays: bool | str, inplace: bool) → quimb.tensor.tensor_core.TensorNetwork[source]¶

Form a compressed MPS for any method that produces a sequence of low-rank ‘left environments’ such as SRC.

Parameters:

tn (TensorNetwork) – The original target tensor network.
local_tns (list[TensorNetwork, ...]) – The tensor network partitioned into each local site.
left_envs (sequence[int, Tensor]) – The left environment tensors, keyed by the site they are the environment for.
left_env_inds (dict[int, sequence[str]]) – The ‘left’ indices of each left environment, typically only one.
contract_opts (dict) – Supplied to tensor_contract() when contracting tensors during the sweep. Values set here take precedence over defaults.
project_opts (dict) – Supplied to tensor_split() when forming the orthogonal projectors. The method should produce a left isometry, for example method="svd:eig". Values set here take precedence over defaults.
equalize_norms (bool or float) – Whether to equalize the norms of the tensors after compression. If an explicit value is given, then the norms will be set to that value, and the overall scaling factor will be accumulated into .exponent.
normalize (bool) – Whether to normalize the final tensor network, making use of the fact that the output tensor network is in right canonical form.
sweep_reverse (bool) – Whether to reverse the order the tensors are inserted, e.g. if site_tags have been reversed, purely for cosmetic ordering of the resulting tensor_map.
permute_arrays (bool or str) – Whether to permute the array indices of the final tensor network into canonical order. If True will use the default order, if any (e.g. MatrixProductState), otherwise if a string this specifies a custom order.
inplace (bool) – Whether to perform the compression inplace or not.

Return type:

TensorNetwork

quimb.tensor.tn1d.compress._src_get_local_noise_tensors(tn, rng, noise_mode, noise_dist, max_bond, Bix, inds, ind_sizes, site_tag)[source]¶

quimb.tensor.tn1d.compress.tensor_network_1d_compress_sdc(tn: quimb.tensor.tensor_core.TensorNetwork, max_bond: int, cutoff=1e-10, site_tags=None, normalize=False, cutoff_mode='rel', permute_arrays=True, optimize='auto-hq', sweep_reverse=False, canonize=True, equalize_norms=False, contract_opts=None, project_opts=None, compress_opts=None, inplace=False, **kwargs)[source]¶

Compress any 1D-like tensor network using ‘Successive Deterministic Compression’ (SDC) https://arxiv.org/abs/2601.19650.

This first forms a sequence of low-rank left environments using successive SVDs, then uses these to form the compressed tensor network with a sweep in the opposite direction. SDC is a deterministic analogue of successive randomized compression (SRC).

Parameters:

tn (TensorNetwork) – The tensor network to compress. Every tensor should have exactly one of the site tags. Each site can have multiple tensors and output indices.
max_bond (int, optional) – The maximum bond dimension to compress to. If not given, only cutoff is used.
cutoff (float, optional) – A dynamic threshold for discarding singular values when forming the low-rank left environments.
site_tags (sequence of str or tag groups, optional) – Tags that identify and order sites. Defaults to tn.site_tags. Each item can group tags as described by parse_site_tag_groups(). The output has one tensor per item.
normalize (bool, optional) – Whether to normalize the final tensor network, making use of the fact that the output tensor network is in right canonical form.
cutoff_mode ({"rel", "rsum2", ...}, optional) – The mode to use when truncating the singular values of the left environments. See tensor_split().
permute_arrays (bool or str, optional) – Whether to permute the array indices of the final tensor network into canonical order. If True will use the default order, otherwise if a string this specifies a custom order.
optimize (str, optional) – The contraction path optimizer to use.
sweep_reverse (bool, optional) – Whether to sweep in the reverse direction, resulting in a left canonical form instead of right canonical.
canonize (bool, optional) – Whether to pseudo canonicalize the initial tensor network. This is not used by the SDC method, and so ignored.
equalize_norms (bool or float, optional) – Whether to equalize the norms of the tensors after compression. If an explicit value is given, then the norms will be set to that value, and the overall scaling factor will be accumulated into .exponent.
contract_opts (dict, optional) – Supplied to tensor_contract(). Values set here take precedence over any defaults.
project_opts (dict, optional) – Supplied to tensor_split() when forming the orthogonal projectors in the final sweep. The method should produce a left isometry, for example method="svd:eig". Values set here take precedence over defaults.
compress_opts (dict, optional) – Supplied to tensor_split() when forming the low-rank left environments, defaulting to method="svd:eig". Values set here take precedence over defaults.
inplace (bool, optional) – Whether to perform the compression inplace or not.
kwargs – Extra keyword arguments are combined into compress_opts, though existing items in compress_opts take precedence over kwargs.

Returns:

The compressed tensor network, with canonical center at site_tags[0] (‘right canonical’ form) or site_tags[-1] (‘left canonical’ form) if sweep_reverse.

Return type:

TensorNetwork

quimb.tensor.tn1d.compress.tensor_network_1d_compress_sdc_oversample(tn: quimb.tensor.tensor_core.TensorNetwork, max_bond: int, max_bond_oversample=None, cutoff=1e-10, cutoff_oversample=0.0, site_tags=None, canonize=True, normalize=False, cutoff_mode='rsum2', cutoff_mode_oversample='rel', permute_arrays=True, optimize='auto-hq', sweep_reverse=False, equalize_norms=False, contract_opts=None, project_opts=None, compress_opts=None, compress_opts_final=None, inplace=False, **kwargs)[source]¶

Compress this 1D-like tensor network using the ‘sdc-oversample’ algorithm, that is, first compressing the tensor network to a larger bond dimension using successive deterministic compression (SDC), then compressing to the desired bond dimension using a direct sweep.

Parameters:

tn (TensorNetwork) – The tensor network to compress. Every tensor should have exactly one of the site tags. Each site can have multiple tensors and output indices.
max_bond (int) – The final maximum bond dimension to compress to.
max_bond_oversample (int, optional) – The intermediate maximum bond dimension to compress to using the SDC algorithm. If not given, this is set as max(round(1.5 * max_bond), max_bond + 10). If given as a float, this is assumed to be a multiplier of max_bond.
cutoff (float, optional) – A dynamic threshold for discarding singular values during the final direct sweep.
cutoff_oversample (float, optional) – A dynamic threshold for discarding singular values when forming the SDC left environments at the intermediate bond dimension.
site_tags (sequence of str or tag groups, optional) – Tags that identify and order sites. Defaults to tn.site_tags. Each item can group tags as described by parse_site_tag_groups(). The output has one tensor per item.
canonize (bool, optional) – Whether to pseudo canonicalize the initial tensor network. This is not used by the SDC method, and so ignored.
normalize (bool, optional) – Whether to normalize the final tensor network, making use of the fact that the output tensor network is in right canonical form.
cutoff_mode ({"rsum2", "rel", ...}, optional) – The mode used in the final canonical sweep. See tensor_split().
cutoff_mode_oversample ({"rel", "rsum2", ...}, optional) – The mode used for the intermediate low-rank left environments, independently of the final sweep. Defaults to "rel".
permute_arrays (bool or str, optional) – Whether to permute the array indices of the final tensor network into canonical order. If True will use the default order, otherwise if a string this specifies a custom order.
optimize (str, optional) – The contraction path optimizer to use.
sweep_reverse (bool, optional) – Whether to sweep in the reverse direction, resulting in a left canonical form instead of right canonical.
equalize_norms (bool or float, optional) – Whether to equalize the norms of the tensors after compression. If an explicit value is given, then the norms will be set to that value, and the overall scaling factor will be accumulated into .exponent.
contract_opts (dict, optional) – Supplied to tensor_contract(). Values set here take precedence over any defaults.
project_opts (dict, optional) – Supplied to tensor_split() when forming the orthogonal projectors in the SDC step. Values set here take precedence over defaults.
compress_opts (dict, optional) – Supplied to tensor_split() in the intermediate SDC step only. Values set here take precedence over defaults.
compress_opts_final (dict, optional) – Options for the final direct sweep, independently of compress_opts. Defaults to exact SVD. Values set here override the final sweep’s max_bond, cutoff, and cutoff_mode.
inplace (bool, optional) – Whether to perform the compression inplace or not.
kwargs – Extra keyword arguments are combined into compress_opts, though existing items in compress_opts take precedence over kwargs.

Returns:

The compressed tensor network, with canonical center at site_tags[0] (‘right canonical’ form) or site_tags[-1] (‘left canonical’ form) if sweep_reverse.

Return type:

TensorNetwork

quimb.tensor.tn1d.compress.tensor_network_1d_compress_sdcr(tn: quimb.tensor.tensor_core.TensorNetwork, max_bond: int, cutoff='auto', site_tags=None, normalize=False, cutoff_mode='rel', permute_arrays=True, optimize='auto-hq', sweep_reverse=False, canonize=True, equalize_norms=False, contract_opts=None, project_opts=None, compress_opts=None, inplace=False, **kwargs)[source]¶

Compress any 1D-like tensor network using ‘Successive Deterministic Compression’ (SDC) https://arxiv.org/abs/2601.19650, but forming the low-rank left environments with a randomized rather than exact SVD. Since the left environments are just a ‘sketch’ and can be very rough, no oversampling or power iterations are used by default.

Parameters:

tn (TensorNetwork) – The tensor network to compress. Every tensor should have exactly one of the site tags. Each site can have multiple tensors and output indices.
max_bond (int) – The maximum bond dimension to compress to, also the rank of the randomized sketches.
cutoff (float or "auto", optional) – A non-cumulative threshold for discarding singular values. With "auto", use only max_bond.
site_tags (sequence of str or tag groups, optional) – Tags that identify and order sites. Defaults to tn.site_tags. Each item can group tags as described by parse_site_tag_groups(). The output has one tensor per item.
normalize (bool, optional) – Whether to normalize the final tensor network, making use of the fact that the output tensor network is in right canonical form.
cutoff_mode ({"rel", "abs"}, optional) – The mode to use when truncating the singular values of the left environments. Defaults to "rel". See tensor_split().
permute_arrays (bool or str, optional) – Whether to permute the array indices of the final tensor network into canonical order. If True will use the default order, otherwise if a string this specifies a custom order.
optimize (str, optional) – The contraction path optimizer to use.
sweep_reverse (bool, optional) – Whether to sweep in the reverse direction, resulting in a left canonical form instead of right canonical.
canonize (bool, optional) – Whether to pseudo canonicalize the initial tensor network. This is not used by the SDC method, and so ignored.
equalize_norms (bool or float, optional) – Whether to equalize the norms of the tensors after compression. If an explicit value is given, then the norms will be set to that value, and the overall scaling factor will be accumulated into .exponent.
contract_opts (dict, optional) – Supplied to tensor_contract(). Values set here take precedence over any defaults.
project_opts (dict, optional) – Supplied to tensor_split() when forming the orthogonal projectors in the final sweep. The method should produce a left isometry, for example method="svd:eig". Values set here take precedence over defaults.
compress_opts (dict, optional) – Supplied to tensor_split() when forming the low-rank left environments, defaulting to method="svd:rand", num_iterations=0, oversample=0. Values set here take precedence over defaults, for example oversample=10 for more accurate sketches, or seed=42 for reproducibility.
inplace (bool, optional) – Whether to perform the compression inplace or not.
kwargs – Extra keyword arguments are combined into compress_opts, though existing items in compress_opts take precedence over kwargs.

Returns:

The compressed tensor network, with canonical center at site_tags[0] (‘right canonical’ form) or site_tags[-1] (‘left canonical’ form) if sweep_reverse.

Return type:

TensorNetwork

quimb.tensor.tn1d.compress.tensor_network_1d_compress_sdcr_oversample(tn: quimb.tensor.tensor_core.TensorNetwork, max_bond: int, max_bond_oversample=None, cutoff=1e-10, cutoff_oversample=0.0, site_tags=None, canonize=True, normalize=False, cutoff_mode='rsum2', cutoff_mode_oversample='rel', permute_arrays=True, optimize='auto-hq', sweep_reverse=False, equalize_norms=False, contract_opts=None, project_opts=None, compress_opts=None, compress_opts_final=None, inplace=False, **kwargs)[source]¶

Compress this 1D-like tensor network using the ‘sdcr-oversample’ algorithm, that is, first compressing the tensor network to a larger bond dimension using successive deterministic compression with random sketches, then compressing to the desired bond dimension using a direct sweep.

Parameters:

tn (TensorNetwork) – The tensor network to compress. Every tensor should have exactly one of the site tags. Each site can have multiple tensors and output indices.
max_bond (int) – The final maximum bond dimension to compress to.
max_bond_oversample (int, optional) – The intermediate maximum bond dimension to compress to using the SDCR algorithm. If not given, this is set as max(round(1.5 * max_bond), max_bond + 10). If given as a float, this is assumed to be a multiplier of max_bond.
cutoff (float, optional) – A dynamic threshold for discarding singular values during the final direct sweep.
cutoff_oversample (float, optional) – A non-cumulative threshold for discarding singular values in the SDCR step, interpreted using cutoff_mode_oversample.
cutoff_mode_oversample ({"rel", "abs"}, optional) – How to interpret the SDCR step’s cutoff. Defaults to "rel", independently of the final direct sweep’s cutoff_mode.
site_tags (sequence of str or tag groups, optional) – Tags that identify and order sites. Defaults to tn.site_tags. Each item can group tags as described by parse_site_tag_groups(). The output has one tensor per item.
canonize (bool, optional) – Whether to pseudo canonicalize the initial tensor network. This is not used by the SDC method, and so ignored.
normalize (bool, optional) – Whether to normalize the final tensor network, making use of the fact that the output tensor network is in right canonical form.
cutoff_mode ({"rsum2", "rel", ...}, optional) – The mode to use when truncating singular values in the final direct sweep. See tensor_split().
permute_arrays (bool or str, optional) – Whether to permute the array indices of the final tensor network into canonical order. If True will use the default order, otherwise if a string this specifies a custom order.
optimize (str, optional) – The contraction path optimizer to use.
sweep_reverse (bool, optional) – Whether to sweep in the reverse direction, resulting in a left canonical form instead of right canonical.
equalize_norms (bool or float, optional) – Whether to equalize the norms of the tensors after compression. If an explicit value is given, then the norms will be set to that value, and the overall scaling factor will be accumulated into .exponent.
contract_opts (dict, optional) – Supplied to tensor_contract(). Values set here take precedence over any defaults.
project_opts (dict, optional) – Supplied to tensor_split() when forming the orthogonal projectors in the SDCR step. Values set here take precedence over defaults.
compress_opts (dict, optional) – Supplied to tensor_split() in the SDCR step, where the randomized defaults are applied. These options only affect the intermediate step and take precedence over defaults.
compress_opts_final (dict, optional) – Options for the final direct sweep, independently of compress_opts. Defaults to exact SVD. Values set here override the final sweep’s max_bond, cutoff, and cutoff_mode.
inplace (bool, optional) – Whether to perform the compression inplace or not.
kwargs – Extra keyword arguments are combined into compress_opts, though existing items in compress_opts take precedence over kwargs.

Returns:

The compressed tensor network, with canonical center at site_tags[0] (‘right canonical’ form) or site_tags[-1] (‘left canonical’ form) if sweep_reverse.

Return type:

TensorNetwork

quimb.tensor.tn1d.compress.tensor_network_1d_compress_src(tn: quimb.tensor.tensor_core.TensorNetwork, max_bond: int, cutoff=0.0, site_tags=None, normalize=False, noise_mode='joint', noise_dist='normal', seed=None, permute_arrays=True, sweep_reverse=False, canonize=True, equalize_norms=False, contract_opts=None, project_opts=None, compress_opts=None, inplace=False, **kwargs)[source]¶

Compress any 1D-like tensor network using ‘Successive Randomized Compression’ (SRC) https://arxiv.org/abs/2504.06475.

Parameters:

tn (TensorNetwork) – The tensor network to compress. Every tensor should have exactly one of the site tags. Each site can have multiple tensors and output indices.
max_bond (int) – The maximum bond dimension to compress to.
cutoff (float, optional) – Unused for SRC, use max_bond.
site_tags (sequence of str or tag groups, optional) – Tags that identify and order sites. Defaults to tn.site_tags. Each item can group tags as described by parse_site_tag_groups(). The output has one tensor per item.
normalize (bool, optional) – Whether to normalize the final tensor network, making use of the fact that the output tensor network is in right canonical form.
noise_mode ({'joint', 'separable', 'symmetric'}, optional) – How to generate the random noise tensors. ‘joint’ generates a single random tensor for all outer indices on a site. ‘separable’ generates a random vector for each outer index. ‘symmetric’ reuses the same random vector for all outer indices on a site.
noise_dist ({"normal", "rademacher"}, optional) – The distribution to use when generating the random noise tensors.
seed (None, int, or random generator, optional) – A random seed or generator to use. If not given, use the backend’s global random state.
permute_arrays (bool or str, optional) – Whether to permute the array indices of the final tensor network into canonical order. If True will use the default order, otherwise if a string this specifies a custom order.
sweep_reverse (bool, optional) – Whether to sweep in the reverse direction, resulting in a left canonical form instead of right canonical.
canonize (bool, optional) – Whether to pseudo canonicalize the initial tensor network. This is always effectively True for the SRC method, and so ignored.
equalize_norms (bool or float, optional) – Whether to equalize the norms of the tensors after compression. If an explicit value is given, then the norms will be set to that value, and the overall scaling factor will be accumulated into .exponent.
contract_opts (dict, optional) – Supplied to tensor_contract(). Values set here take precedence over any defaults.
project_opts (dict, optional) – Supplied to tensor_split() when forming the orthogonal projectors. The method should product a left isometry, for example method="svd:eig". Values set here take precedence over defaults.
inplace (bool, optional) – Whether to perform the compression inplace or not.
kwargs – Extra keyword arguments are combined into contract_opts, though existing items in contract_opts take precedence over kwargs.

Returns:

The compressed tensor network, with canonical center at site_tags[0] (‘right canonical’ form) or site_tags[-1] (‘left canonical’ form) if sweep_reverse.

Return type:

TensorNetwork

quimb.tensor.tn1d.compress.tensor_network_1d_compress_src_oversample(tn: quimb.tensor.tensor_core.TensorNetwork, max_bond: int, max_bond_oversample=None, cutoff=1e-10, cutoff_oversample=0.0, noise_mode='joint', noise_dist='normal', seed=None, site_tags=None, canonize=True, normalize=False, cutoff_mode='rsum2', permute_arrays=True, optimize='auto-hq', sweep_reverse=False, equalize_norms=False, contract_opts=None, project_opts=None, compress_opts=None, compress_opts_final=None, inplace=False, **kwargs)[source]¶

Compress this 1D-like tensor network using the ‘src first’ algorithm, i.e. src with oversampling, that is, first compressing the tensor network to a larger bond dimension using the ‘src’ (successive randomized compression, https://arxiv.org/abs/2504.06475) algorithm, then compressing to the desired bond dimension using a direct sweep.

Parameters:

tn (TensorNetwork) – The tensor network to compress. Every tensor should have exactly one of the site tags. Each site can have multiple tensors and output indices.
max_bond (int) – The final maximum bond dimension to compress to.
max_bond_oversample (int, optional) – The intermediate maximum bond dimension to compress to using the ‘src’ algorithm. If not given and max_bond is, this is set as max(round(1.5 * max_bond), max_bond + 10). If given as a float, this is assumed to be a multiplier of max_bond.
cutoff (float, optional) – A dynamic threshold for discarding singular values when compressing during the final direct sweep.
cutoff_oversample (float, optional) – Unused for SRC.
noise_mode ({'separable', 'symmetric', 'joint'}, optional) – How to generate the random noise tensors for the SRC step.
noise_dist ({"normal", "rademacher"}, optional) – The distribution to use when generating the random noise tensors for the SRC step.
seed (None, int, or random generator, optional) – A random seed or generator to use for the SRC step. If not given, use the backend’s global random state.
site_tags (sequence of str or tag groups, optional) – Tags that identify and order sites. Defaults to tn.site_tags. Each item can group tags as described by parse_site_tag_groups(). The output has one tensor per item.
canonize (bool, optional) – Whether to pseudo canonicalize the initial tensor network.
normalize (bool, optional) – Whether to normalize the final tensor network, making use of the fact that the output tensor network is in right canonical form.
cutoff_mode ({"rsum2", "rel", ...}, optional) – The mode to use when truncating the singular values of the decomposed tensors during the final direct sweep.
permute_arrays (bool or str, optional) – Whether to permute the array indices of the final tensor network into canonical order. If True will use the default order, otherwise if a string this specifies a custom order.
optimize (str, optional) – The contraction path optimizer to use.
sweep_reverse (bool, optional) – Whether to sweep in the reverse direction, resulting in a left canonical form instead of right canonical.
equalize_norms (bool or float, optional) – Whether to equalize the norms of the tensors after compression. If an explicit value is given, then the norms will be set to that value, and the overall scaling factor will be accumulated into .exponent.
contract_opts (dict, optional) – Supplied to tensor_contract(). Values set here take precedence over any defaults.
project_opts (dict, optional) – Supplied to tensor_split() when forming the orthogonal projectors in the SRC step. The method should product a left isometry, for example method="svd:eig". Values set here take precedence over defaults.
inplace (bool, optional) – Whether to perform the compression inplace or not.
compress_opts (dict, optional) – Supplied to tensor_split() during the final direct sweep. Values set here take precedence over defaults.
compress_opts_final (dict, optional) – Options for the final direct sweep. Values set here take precedence over compress_opts and kwargs, which also target the final sweep for this method.
kwargs – Extra keyword arguments are combined into compress_opts, though existing items in compress_opts take precedence over kwargs.

Returns:

The compressed tensor network.

Return type:

TensorNetwork

quimb.tensor.tn1d.compress.tensor_network_1d_compress_srcmps(tn: quimb.tensor.tensor_core.TensorNetwork, max_bond: int, cutoff=0.0, tn_fit=None, site_tags=None, normalize=False, noise_dist='normal', seed=None, permute_arrays=True, sweep_reverse=False, canonize=True, equalize_norms=False, contract_opts=None, project_opts=None, compress_opts=None, inplace=False, **kwargs)[source]¶

Compress any 1D-like tensor network using ‘Successive Randomized Compression’ (SRC) https://arxiv.org/abs/2504.06475 but using a random or a supplied MPS as the ‘sampling noise’.

Parameters:

tn (TensorNetwork) – The tensor network to compress. Every tensor should have exactly one of the site tags. Each site can have multiple tensors and output indices.
max_bond (int) – The maximum bond dimension to compress to.
cutoff (float, optional) – Unused for SRC, use max_bond.
tn_fit (TensorNetwork, dict, or str, optional) – The MPS specificing the sampling noise (its bond dimension effectively sets the compression rank). If not given, a random MPS with bond dimension max_bond is used. If a string or dict, this is used to construct the MPS from tn.
site_tags (sequence of str or tag groups, optional) – Tags that identify and order sites. Defaults to tn.site_tags. Each item can group tags as described by parse_site_tag_groups(). The output has one tensor per item.
normalize (bool, optional) – Whether to normalize the final tensor network, making use of the fact that the output tensor network is in right canonical form.
noise_dist ({"normal", "rademacher"}, optional) – The distribution to use when generating the random sampling MPS, only relevant if tn_fit is not supplied.
seed (None, int, or random generator, optional) – A random seed or generator to use when generating the random sampling MPS. If not given, use the backend’s global random state. This is only relevant if tn_fit is not supplied.
permute_arrays (bool or str, optional) – Whether to permute the array indices of the final tensor network into canonical order. If True will use the default order, otherwise if a string this specifies a custom order.
canonize (bool, optional) – Whether to pseudo canonicalize the initial tensor network.
sweep_reverse (bool, optional) – Whether to sweep in the reverse direction, resulting in a left canonical form instead of right canonical.
equalize_norms (bool or float, optional) – Whether to equalize the norms of the tensors after compression. If an explicit value is given, then the norms will be set to that value, and the overall scaling factor will be accumulated into .exponent.
contract_opts (dict, optional) – Supplied to tensor_contract(). Values set here take precedence over any defaults.
project_opts (dict, optional) – Supplied to tensor_split() when forming the orthogonal projectors. The method should produce a left isometry, for example method="svd:eig". Values set here take precedence over defaults.
inplace (bool, optional) – Whether to perform the compression inplace or not.
kwargs – Extra keyword arguments are combined into contract_opts, though existing items in contract_opts take precedence over kwargs.

Returns:

The compressed tensor network.

Return type:

TensorNetwork

quimb.tensor.tn1d.compress.tensor_network_1d_compress_srcmps_oversample(tn: quimb.tensor.tensor_core.TensorNetwork, max_bond: int, max_bond_oversample=None, cutoff=1e-10, cutoff_oversample=0.0, tn_fit=None, noise_dist='normal', seed=None, site_tags=None, canonize=True, normalize=False, cutoff_mode='rsum2', permute_arrays=True, optimize='auto-hq', sweep_reverse=False, equalize_norms=False, contract_opts=None, project_opts=None, compress_opts=None, compress_opts_final=None, inplace=False, **kwargs)[source]¶

Compress this 1D-like tensor network using the ‘srcmps-oversample’ algorithm, i.e. src with oversampling and matrix product state noise, that is, first compressing the tensor network to a larger bond dimension using the ‘src’ (successive randomized compression, https://arxiv.org/abs/2504.06475) algorithm, then compressing to the desired bond dimension using a direct sweep.

Parameters:

tn (TensorNetwork) – The tensor network to compress. Every tensor should have exactly one of the site tags. Each site can have multiple tensors and output indices.
max_bond (int) – The final maximum bond dimension to compress to.
max_bond_oversample (int, optional) – The intermediate maximum bond dimension to compress to using the ‘srcmps’ algorithm. If not given and max_bond is, this is set as max(round(1.5 * max_bond), max_bond + 10). If given as a float, this is assumed to be a multiplier of max_bond.
cutoff (float, optional) – A dynamic threshold for discarding singular values when compressing during the final direct sweep.
cutoff_oversample (float, optional) – Unused for SRC.
tn_fit (TensorNetwork, optional) – The MPS specificing the sampling noise (its bond dimension effectively sets the compression rank).
noise_dist ({"normal", "rademacher"}, optional) – The distribution to use when generating the random sampling MPS, only relevant if tn_fit is not supplied.
seed (None, int, or random generator, optional) – A random seed or generator to use for the SRCMPS step. If not given, use the backend’s global random state.
site_tags (sequence of str or tag groups, optional) – Tags that identify and order sites. Defaults to tn.site_tags. Each item can group tags as described by parse_site_tag_groups(). The output has one tensor per item.
canonize (bool, optional) – Whether to pseudo canonicalize the initial tensor network.
normalize (bool, optional) – Whether to normalize the final tensor network, making use of the fact that the output tensor network is in right canonical form.
cutoff_mode ({"rsum2", "rel", ...}, optional) – The mode to use when truncating the singular values of the decomposed tensors during the final direct sweep.
permute_arrays (bool or str, optional) – Whether to permute the array indices of the final tensor network into canonical order. If True will use the default order, otherwise if a string this specifies a custom order.
optimize (str, optional) – The contraction path optimizer to use.
sweep_reverse (bool, optional) – Whether to sweep in the reverse direction, resulting in a left canonical form instead of right canonical.
equalize_norms (bool or float, optional) – Whether to equalize the norms of the tensors after compression. If an explicit value is given, then the norms will be set to that value, and the overall scaling factor will be accumulated into .exponent.
contract_opts (dict, optional) – Supplied to tensor_contract(). Values set here take precedence over any defaults.
project_opts (dict, optional) – Supplied to tensor_split() when forming the orthogonal projectors in the SRC step. The method should produce a left isometry, for example method="svd:eig". Values set here take precedence over defaults.
compress_opts (dict, optional) – Supplied to tensor_split() during the final direct sweep. Values set here take precedence over defaults.
compress_opts_final (dict, optional) – Options for the final direct sweep. Values set here take precedence over compress_opts and kwargs, which also target the final sweep for this method.
inplace (bool, optional) – Whether to perform the compression inplace or not.
kwargs – Extra keyword arguments are combined into compress_opts, though existing items in compress_opts take precedence over kwargs.

Returns:

The compressed tensor network.

Return type:

TensorNetwork

quimb.tensor.tn1d.compress._conjugate_fit_update(fit_update: quimb.tensor.tensor_core.Tensor) → None[source]¶

Conjugate a local fit update in place.

For fermionic data, also phase every dual axis of the update. This includes exposed fit bonds. It is a local adjoint, not the network-level conjugation used to build the overlap.

quimb.tensor.tn1d.compress._tn1d_fit_sum_sweep_1site(tn_fit: quimb.tensor.tensor_core.TensorNetwork, tn_overlaps: list[quimb.tensor.tensor_core.TensorNetwork], site_tags: list[str], max_bond=None, cutoff=0.0, envs=None, prepare=True, reverse=False, compute_tdiff=True, optimize='auto-hq')[source]¶: Core sweep of the 1-site 1D fit algorithm.

quimb.tensor.tn1d.compress._tn1d_fit_sum_sweep_2site(tn_fit: quimb.tensor.tensor_core.TensorNetwork, tn_overlaps: list[quimb.tensor.tensor_core.TensorNetwork], site_tags: list[str], max_bond=None, cutoff=1e-10, envs=None, prepare=True, reverse=False, optimize='auto-hq', compute_tdiff=True, **compress_opts)[source]¶: Core sweep of the 2-site 1D fit algorithm.

quimb.tensor.tn1d.compress.tensor_network_1d_compress_fit(tns: quimb.tensor.tensor_core.TensorNetwork | list[quimb.tensor.tensor_core.TensorNetwork], max_bond=None, cutoff=None, tn_fit=None, bsz='auto', initial_bond_dim=8, max_iterations=10, tol=0.0, site_tags=None, cutoff_mode='rsum2', sweep_sequence='RL', noise_dist='normal', seed=None, normalize=False, permute_arrays=True, optimize='auto-hq', canonize=True, sweep_reverse=False, equalize_norms=False, compress_opts=None, inplace_fit=False, inplace=False, progbar=False, **kwargs)[source]¶

Compress any 1D-like (can have multiple tensors per site) tensor network or sum of tensor networks to an exactly 1D (one tensor per site) tensor network of bond dimension max_bond using the 1-site or 2-site variational fitting (or ‘DMRG-style’) method. The tensor network(s) can have arbitrary inner and outer structure.

This method has the lowest scaling of the standard 1D compression methods and can also provide the most accurate compression, but the actual speed and accuracy depend on the number of iterations required and initial guess, making it a more ‘hands-on’ method.

It’s also the only method to support fitting to a sum of tensor networks directly, rather than having to forming the explicitly summed TN first.

Parameters:

tns (TensorNetwork or Sequence[TensorNetwork]) – The tensor network or tensor networks to compress. Each tensor network should have the same outer index structure, and within each tensor network every tensor should have exactly one of the site tags.
max_bond (int) – The maximum bond dimension to compress to. If not given, this is set as the maximum bond dimension of the initial guess tensor network, if any, else infinite for bsz=2.
cutoff (float, optional) – A dynamic threshold for discarding singular values when compressing. This is only relevant for the 2-site sweeping algorithm (bsz=2), where it defaults to 1e-10.
tn_fit (TensorNetwork, dict, or str, optional) – An initial guess for the compressed tensor network. It should matching outer indices and site tags with tn. If a dict, this is assumed to be options to supply to tensor_network_1d_compress to construct the initial guess, inheriting various defaults like initial_bond_dim. If a string, e.g. "zipup", this is shorthand for that compression method with default settings. If not given, a random 1D tensor network will be used.
bsz ({"auto", 1, 2}, optional) – The size of the block to optimize while sweeping. If "auto", this will be inferred from the value of max_bond and cutoff.
initial_bond_dim (int, optional) – The initial bond dimension to use when creating the initial guess. This is only relevant if tn_fit is not given. For each sweep the allowed bond dimension is doubled, up to max_bond. For 1-site this occurs via explicit bond expansion, while for 2-site it occurs during the 2-site tensor decomposition.
max_iterations (int, optional) – The maximum number of variational sweeps to perform.
tol (float, optional) – The convergence tolerance, in terms of local tensor distance normalized. If zero, there will be exactly max_iterations sweeps.
site_tags (sequence of str or tag groups, optional) – Tags that identify and order sites. Defaults to tn.site_tags. Each item can group tags as described by parse_site_tag_groups(). The output has one tensor per item.
cutoff_mode ({"rsum2", "rel", ...}, optional) – The mode to use when truncating the singular values of the decomposed tensors. See tensor_split(), if using the 2-site sweeping algorithm.
sweep_sequence (str, optional) – The sequence of sweeps to perform, e.g. "LR" means first sweep left to right, then right to left. The sequence is cycled. The final canonical form of the output tensor network depends on the last sweep direction and sweep_reverse.
noise_dist ({"normal", "rademacher"}, optional) – The distribution to use when generating the random sampling MPS, only relevant if tn_fit is not supplied.
seed (None, int, or random generator, optional) – A random seed or generator to use when generating the initial guess. If not given, use the backend’s global random state. This is only relevant if tn_fit is not supplied.
normalize (bool, optional) – Whether to normalize the final tensor network, making use of the fact that the output tensor network is in left or right canonical form.
permute_arrays (bool or str, optional) – Whether to permute the array indices of the final tensor network into canonical order. If True will use the default order, otherwise if a string this specifies a custom order.
optimize (str, optional) – The contraction path optimizer to use.
canonize (bool, optional) – Dummy argument to match the signature of other compression methods.
sweep_reverse (bool, optional) – Whether to sweep in the reverse direction, swapping whether the final tensor network is in right or left canonical form, which also depends on the last sweep direction.
equalize_norms (bool or float, optional) – Whether to equalize the norms of the tensors after compression. If an explicit value is given, then the norms will be set to that value, and the overall scaling factor will be accumulated into .exponent.
compress_opts (dict, optional) – Supplied to tensor_split(), if using the 2-site sweeping algorithm. Values set here take precedence over defaults.
inplace_fit (bool, optional) – Whether to perform the compression inplace on the initial guess tensor network, tn_fit, if supplied.
inplace (bool, optional) – Whether to perform the compression inplace on the target tensor network supplied, or tns[0] if a sequence to sum is supplied.
progbar (bool, optional) – Whether to show a progress bar. Note the progress bar shows the maximum change of any single tensor norm, not the global change in norm or truncation error.
kwargs – Extra keyword arguments are combined into compress_opts, though existing items in compress_opts take precedence over kwargs.

Returns:

The compressed tensor network. Depending on sweep_reverse and the last sweep direction, the canonical center will be at either L: site_tags[0] or R: site_tags[-1], or the opposite if sweep_reverse.

Return type:

TensorNetwork

quimb.tensor.tn1d.compress.tensor_network_1d_compress_fit_guess(tn: quimb.tensor.tensor_core.TensorNetwork | list[quimb.tensor.tensor_core.TensorNetwork], guess: str, max_bond=None, cutoff=1e-10, cutoff_fit=0.0, bsz=1, max_iterations=8, canonize=True, **kwargs)[source]¶

Compress any 1D-like (can have multiple tensors per site) tensor network to an exactly 1D (one tensor per site) tensor network of bond dimension max_bond using by default 1-site variational fitting (or ‘DMRG-style’) method starting with a non-random guess tensor network, e.g. from the cheap zip-up or projector methods.

Parameters:

tn (TensorNetwork) – The tensor network to compress. Every tensor should have exactly one of the site tags. Each site can have multiple tensors and output indices.
guess (str) – The method to use to generate the initial guess.
max_bond (int) – The maximum bond dimension to compress to.
cutoff (float, optional) – The cutoff used for the guess compression method.
cutoff_fit (float, optional) – The cutoff used for the fit compression method.
bsz (int, optional) – The block size to use for the variational fitting sweep.
max_iterations (int, optional) – The maximum number of variational sweeps to perform.
canonize (bool, optional) – Whether to canonicalize the guess tensor network.
kwargs – Supplied to tensor_network_1d_compress_fit().

Returns:

The compressed tensor network.

Return type:

TensorNetwork

quimb.tensor.tn1d.compress.tensor_network_1d_compress_fit_zipup¶

quimb.tensor.tn1d.compress.tensor_network_1d_compress_fit_projector¶

quimb.tensor.tn1d.compress.tensor_network_1d_compress_fit_oversample(tn: quimb.tensor.tensor_core.TensorNetwork | list[quimb.tensor.tensor_core.TensorNetwork], max_bond=None, max_bond_oversample=None, cutoff=1e-10, cutoff_fit=0.0, bsz=1, site_tags=None, noise_dist='normal', seed=None, canonize=True, normalize=False, cutoff_mode='rsum2', permute_arrays=True, optimize='auto-hq', sweep_reverse=False, equalize_norms=False, compress_opts=None, compress_opts_final=None, inplace=False, **kwargs)[source]¶

Compress this 1D-like tensor network using the ‘fit-oversample’ algorithm, that is, first compressing the tensor network to a larger bond dimension using the variational ‘fit’ algorithm, then compressing to the desired bond dimension using a direct sweep.

Parameters:

tn (TensorNetwork) – The tensor network to compress. Every tensor should have exactly one of the site tags. Each site can have multiple tensors and output indices.
max_bond (int) – The final maximum bond dimension to compress to.
max_bond_oversample (int, optional) – The intermediate maximum bond dimension to compress to using the ‘fit’ algorithm. If not given and max_bond is, this is set as max(round(1.5 * max_bond), max_bond + 10). If given as a float, this is assumed to be a multiplier of max_bond.
cutoff (float, optional) – A dynamic threshold for discarding singular values when compressing during the final direct sweep.
cutoff_fit (float, optional) – A dynamic threshold for discarding singular values when compressing to the intermediate bond dimension using the ‘fit’ algorithm (only relevant if bsz=2).
bsz ({1, 2}, optional) – The block size to use for the variational fitting sweep.
site_tags (sequence of str or tag groups, optional) – Tags that identify and order sites. Defaults to tn.site_tags. Each item can group tags as described by parse_site_tag_groups(). The output has one tensor per item.
noise_dist ({"normal", "rademacher"}, optional) – The distribution to use when generating the random sampling MPS, only relevant if tn_fit is not supplied.
seed (None, int, or random generator, optional) – A random seed or generator to use for the fit step. If not given, use the backend’s global random state.
canonize (bool, optional) – Whether to pseudo canonicalize the initial tensor network.
normalize (bool, optional) – Whether to normalize the final tensor network, making use of the fact that the output tensor network is in right canonical form.
cutoff_mode ({"rsum2", "rel", ...}, optional) – The mode to use when truncating the singular values of the decomposed tensors. See tensor_split().
permute_arrays (bool or str, optional) – Whether to permute the array indices of the final tensor network into canonical order. If True will use the default order, otherwise if a string this specifies a custom order.
optimize (str, optional) – The contraction path optimizer to use.
sweep_reverse (bool, optional) – Whether to sweep in the reverse direction, resulting in a left canonical form instead of right canonical.
equalize_norms (bool or float, optional) – Whether to equalize the norms of the tensors after compression. If an explicit value is given, then the norms will be set to that value, and the overall scaling factor will be accumulated into .exponent.
inplace (bool, optional) – Whether to perform the compression inplace or not.
compress_opts (dict, optional) – Supplied to tensor_split() during the final direct sweep. Values set here take precedence over defaults.
compress_opts_final (dict, optional) – Options for the final direct sweep. Values set here take precedence over compress_opts and kwargs, which also target the final sweep for this method.
kwargs – Extra keyword arguments are combined into compress_opts, though existing items in compress_opts take precedence over kwargs.

Returns:

The compressed tensor network, with canonical center at site_tags[0] (‘right canonical’ form) or site_tags[-1] (‘left canonical’ form) if sweep_reverse.

Return type:

TensorNetwork

quimb.tensor.tn1d.compress._TN1D_COMPRESS_METHODS¶

quimb.tensor.tn1d.compress._TN1D_COMPRESS_DEFAULT_CUTOFFS¶

quimb.tensor.tn1d.compress.tensor_network_1d_compress(tn: quimb.tensor.tensor_core.TensorNetwork | list[quimb.tensor.tensor_core.TensorNetwork], max_bond=None, cutoff='auto', method='dm', site_tags=None, canonize=True, permute_arrays=True, optimize='auto-hq', sweep_reverse=False, equalize_norms=False, inplace=False, **kwargs) → quimb.tensor.tensor_core.TensorNetwork[source]¶

Compress a 1D-like tensor network, or sequence of such networks representing a sum, using the specified method, into an exactly 1D tensor network of bond dimension max_bond. The only requirement is that each tensor has exactly one of the site tags, which determines which site it will be grouped and compressed into. Each such ‘site’ can have multiple tensors and output indices. Long range bonds are handled automatically by inserting identities, but note that this function is intended for 1D-like open boundary tensor networks and always produces an open boundary compressed tensor network. See tensor_network_ag_compress() for arbitrary geometry tensor network compression methods for non 1D-like TNs.

Parameters:

tn (TensorNetwork or sequence of TensorNetwork) – The tensor network(s) to compress. Every tensor should have exactly one of the site tags. Each site can have multiple tensors and output indices. If a sequence is given, these tensor networks will be compressed as their sum (only supported by the ‘fit’ method).
max_bond (int) – The maximum bond dimension to compress to.
cutoff (float or "auto", optional) – A dynamic threshold for discarding singular values when compressing. With "auto", use 0.0 for ranomized svd like methods, else 1e-10. For oversampling methods, this is the cutoff of the final direct sweep, not the intermediate step.
method (str or callable, optional) –
The compression method to use. A callable is passed the same arguments as a built-in 1D method. The named options are:
- "direct" : direct SVD sweep.
- "dm" : density matrix method.
- "zipup" : zip-up method.
- "zipup-first" or "zipup-oversample" : zip-up with oversampling.
- "sdc": successive deterministic compression method.
- "sdc-oversample" : successive deterministic compression with oversampling.
- "sdcr": successive deterministic compression, with randomized rather than exact SVDs.
- "sdcr-oversample" : randomized successive deterministic compression with oversampling.
- "src": successive randomized compression method.
- "src-first" or "src-oversample" : successive randomized compression with oversampling.
- "srcmps": successive randomized compression method using an MPS as the sampling noise.
- "srcmps-first" or "srcmps-oversample" : successive randomized compression using an MPS as the sampling noise with oversampling.
- "fit" : variational fitting (DMRG-style) method.
- "fit-{method}" : variational fitting starting from a guess generated using {method}, e.g. "fit-zipup".
- "fit-oversample" : variational fitting with oversampling.
- any other method supported by tensor_network_ag_compress().
Oversampling methods first compress to max_bond_oversample (typically chosen as 1.5 or 2x max_bond) using the specified method, then compress to max_bond using a direct sweep.
site_tags (sequence of str or tag groups, optional) – Tags that identify and order sites. Defaults to tn.site_tags. Each item can group tags as described by parse_site_tag_groups(). The output has one tensor per item.
canonize (bool, optional) – Whether to perform canonicalization, pseudo or otherwise depending on the method, before compressing. Ignored for method='dm' and method='fit'.
permute_arrays (bool or str, optional) – Whether to permute the array indices of the final tensor network into canonical order. If True will use the default order, otherwise if a string this specifies a custom order.
optimize (str, optional) – The contraction path optimizer to use.
sweep_reverse (bool, optional) – Whether to sweep in the reverse direction, resulting in a left canonical form instead of right canonical (for the fit method, this also depends on the last sweep direction).
equalize_norms (bool or float, optional) – Whether to equalize the norms of the tensors after compression. If an explicit value is given, then the norms will be set to that value, and the overall scaling factor will be accumulated into .exponent.
inplace (bool, optional) – Whether to perform the compression inplace.
kwargs – Supplied to the chosen compression method.

Return type:

TensorNetwork

quimb.tensor.tn1d.compress.mps_gate_with_mpo_lazy(mps, mpo, inplace=False)[source]¶: Apply an MPO to an MPS lazily, i.e. nothing is contracted, but the new TN object has the same outer indices as the original MPS.

quimb.tensor.tn1d.compress.mps_gate_with_mpo_direct(mps, mpo, max_bond=None, cutoff=1e-10, inplace=False, **compress_opts)[source]¶

Apply an MPO to an MPS using the boundary compression method, that is, explicitly contracting site-wise to form a MPS-like TN, canonicalizing in one direction, then compressing in the other. This has the same scaling as the density matrix (dm) method, but a larger prefactor. It can still be faster for small bond dimensions however, and is potentially higher precision since it works in the space of singular values directly rather than singular values squared. It is not quite optimal in terms of error due to the compounding errors of the SVDs.

Parameters:

mps (MatrixProductState) – The MPS to gate.
mpo (MatrixProductOperator) – The MPO to gate with.
max_bond (int) – The maximum bond dimension to compress to.
cutoff (float, optional) – A dynamic threshold for discarding singular values when compressing.
compress_opts – Supplied to tensor_split().

quimb.tensor.tn1d.compress.mps_gate_with_mpo_dm(mps, mpo, max_bond=None, cutoff=1e-10, inplace=False, **compress_opts)[source]¶

Gate this MPS with an MPO, using the density matrix compression method.

Parameters:

mps (MatrixProductState) – The MPS to gate.
mpo (MatrixProductOperator) – The MPO to gate with.
max_bond (int, optional) – The maximum bond dimension to keep when compressing the double layer tensor network, if any.
cutoff (float, optional) – The truncation error to use when compressing the double layer tensor network, if any.
compress_opts – Supplied to tensor_split().

quimb.tensor.tn1d.compress.mps_gate_with_mpo_zipup(mps, mpo, max_bond=None, cutoff=1e-10, canonize=True, optimize='auto-hq', **compress_opts)[source]¶

Apply an MPO to an MPS using the ‘zip-up’ algorithm due to ‘Minimally Entangled Typical Thermal State Algorithms’, E.M. Stoudenmire & Steven R. White (https://arxiv.org/abs/1002.1305).

Parameters:

mps (MatrixProductState) – The MPS to gate.
mpo (MatrixProductOperator) – The MPO to gate with.
max_bond (int) – The maximum bond dimension to compress to.
cutoff (float, optional) – A dynamic threshold for discarding singular values when compressing.
site_tags (sequence of str or tag groups, optional) – Tags that identify and order sites. Defaults to tn.site_tags. Each item can group tags as described by parse_site_tag_groups(). The output has one tensor per item.
canonize (bool, optional) – Whether to pseudo canonicalize the initial tensor network.
normalize (bool, optional) – Whether to normalize the final tensor network, making use of the fact that the output tensor network is in right canonical form.
permute_arrays (bool or str, optional) – Whether to permute the array indices of the final tensor network into canonical order. If True will use the default order, otherwise if a string this specifies a custom order.
optimize (str, optional) – The contraction path optimizer to use.
compress_opts – Supplied to tensor_split().

Returns:

The compressed MPS, in right canonical form.

Return type:

MatrixProductState

quimb.tensor.tn1d.compress.mps_gate_with_mpo_zipup_first(mps, mpo, max_bond=None, max_bond_oversample=None, cutoff=1e-10, cutoff_oversample='auto', canonize=True, optimize='auto-hq', **compress_opts)[source]¶

Apply an MPO to an MPS by first using the zip-up method with a larger bond dimension, then doing a regular compression sweep to the target final bond dimension. This avoids forming an intermediate MPS with bond dimension mps.max_bond() * mpo.max_bond().

Parameters:

mps (MatrixProductState) – The MPS to gate.
mpo (MatrixProductOperator) – The MPO to gate with.
max_bond (int) – The target final bond dimension.
max_bond_oversample (int, optional) – The maximum bond dimension to use when zip-up compressing the double layer tensor network. If not given, defaults to 2 * max_bond. Needs to be smaller than mpo.max_bond() for any savings.
cutoff (float, optional) – The truncation error to use when performing the final regular compression sweep.
cutoff_oversample (float or "auto", optional) – The singular-value cutoff for the zip-up compression. With "auto", use 0.0 for randomized SVD and 1e-10 for exact decompositions, independently of the final sweep’s cutoff.
canonize (bool, optional) – Whether to pseudo canonicalize the initial tensor network.
optimize (str, optional) – The contraction path optimizer to use.
compress_opts – Supplied to tensor_network_1d_compress_zipup_oversample(). Extra split options affect the intermediate zipup step. Use compress_opts_final to configure the final direct sweep.

Returns:

The compressed MPS, in right canonical form.

Return type:

MatrixProductState

quimb.tensor.tn1d.compress.mps_gate_with_mpo_fit(mps, mpo, max_bond, **kwargs)[source]¶

Gate an MPS with an MPO using the variational fitting or DMRG-style method.

Parameters:

mps (MatrixProductState) – The MPS to gate.
mpo (MatrixProductOperator) – The MPO to gate with.
max_bond (int) – The maximum bond dimension to compress to.

Returns:

The gated MPS.

Return type:

MatrixProductState

quimb.tensor.tn1d.compress.mps_gate_with_mpo_autofit(self, mpo, max_bond, cutoff=0.0, init_guess=None, **fit_opts)[source]¶

Fit a MPS to a MPO applied to an MPS using geometry generic versions of either ALS or autodiff. This is usually much less efficient that using the 1D specific methods.

Some nice alternatives to the default fit_opts:

method=”autodiff”

method=”als”, solver=”lstsq”

quimb.tensor.tn1d.compress.mps_gate_with_mpo_projector(self, mpo, max_bond, cutoff=1e-10, canonize=True, canonize_opts=None, inplace=False, **compress_opts)[source]¶: Apply an MPO to an MPS using local projectors, in the style of CTMRG or HOTRG, without using information beyond the neighboring 4 tensors.