Bond dimension

Reference for changing the bond dimension of a state — expanding or truncating its virtual spaces — and for inspecting those virtual spaces directly. For a task-oriented walkthrough see Controlling bond dimension; the full, canonical docstrings for the whole package live in the Library index.

Interface

MPSKit.changebonds Function

changebonds(ψ::AbstractMPS, H, alg, envs) -> ψ′, envs′
changebonds(ψ::AbstractMPS, alg) -> ψ′

Change the bond dimension of ψ using the algorithm alg, and return the new ψ and the new envs. For AbstractInfiniteMPS, changebonds returns new environments without modifying the one provided. changedbonds! can modify both the provided state and environments, depending on the algorithm. For FiniteMPS, changebonds also modifies the environments.

See also: SvdCut, RandExpand, VUMPSSvdCut, OptimalExpand

Examples

Growing the bond dimension of a product state with OptimalExpand, which expands each bond with directions orthogonal to the current state (using the environments of H):

julia> Z = TensorMap(Float64[1 0; 0 -1], ℂ^2, ℂ^2);

julia> ψ = FiniteMPS(ones(Float64, (ℂ^2)^4));

julia> H = FiniteMPOHamiltonian(fill(ℂ^2, 4), ((i, i + 1) => Z ⊗ Z for i in 1:3));

julia> dim(left_virtualspace(ψ, 3))
1

julia> ψ′, envs = changebonds(ψ, H, OptimalExpand(; trunc = truncrank(4)));

julia> dim(left_virtualspace(ψ′, 3))
2

Note

A bond is only expanded if there is something to expand it with. If the projection of the two-site update onto the orthogonal complement of the current state vanishes — for instance when the state is already an exact eigenstate of the local terms, or when the operator does not couple into a symmetry sector yet — that bond is left untouched. Replacing Z ⊗ Z by X ⊗ X above illustrates this: ones(Float64, (ℂ^2)^4) is an eigenstate of every X ⊗ X term, so every bond stays at dimension 1.

source

MPSKit.changebonds! Function

changebonds(ψ::AbstractMPS, H, alg, envs) -> ψ′, envs′
changebonds(ψ::AbstractMPS, alg) -> ψ′

Change the bond dimension of ψ using the algorithm alg, and return the new ψ and the new envs. For AbstractInfiniteMPS, changebonds returns new environments without modifying the one provided. changedbonds! can modify both the provided state and environments, depending on the algorithm. For FiniteMPS, changebonds also modifies the environments.

See also: SvdCut, RandExpand, VUMPSSvdCut, OptimalExpand

Examples

Growing the bond dimension of a product state with OptimalExpand, which expands each bond with directions orthogonal to the current state (using the environments of H):

julia> Z = TensorMap(Float64[1 0; 0 -1], ℂ^2, ℂ^2);

julia> ψ = FiniteMPS(ones(Float64, (ℂ^2)^4));

julia> H = FiniteMPOHamiltonian(fill(ℂ^2, 4), ((i, i + 1) => Z ⊗ Z for i in 1:3));

julia> dim(left_virtualspace(ψ, 3))
1

julia> ψ′, envs = changebonds(ψ, H, OptimalExpand(; trunc = truncrank(4)));

julia> dim(left_virtualspace(ψ′, 3))
2

Note

A bond is only expanded if there is something to expand it with. If the projection of the two-site update onto the orthogonal complement of the current state vanishes — for instance when the state is already an exact eigenstate of the local terms, or when the operator does not couple into a symmetry sector yet — that bond is left untouched. Replacing Z ⊗ Z by X ⊗ X above illustrates this: ones(Float64, (ℂ^2)^4) is an eigenstate of every X ⊗ X term, so every bond stays at dimension 1.

source

Expansion and truncation algorithms

MPSKit.OptimalExpand Type

struct OptimalExpand{S} <: MPSKit.Algorithm

An algorithm that expands the given mps as described in Zauner-Stauber et al. Phys. Rev. B 97 (2018), by selecting the dominant contributions of a two-site updated MPS tensor, orthogonal to the original ψ.

The expansion is state-preserving: the added directions are connected through a zero block, so that the expanded state represents the same physical state as the original one (as required for e.g. TDVP).

Note

trunc bounds how much is added to each bond, not the total bond dimension that is kept. It is applied to the two-site update projected onto the orthogonal complement of the current state, so truncrank(k) grows every bond by at most k — capped by the dimension of the local two-site complement, which is why a bond can grow by less than k, or not at all. The trunc of SvdCut, and of the drivers DMRG and TDVP, has the other meaning: it bounds what is kept.

Note

The projected block is normalized before the decomposition, so a value-based strategy (trunctol, truncerror) selects a fraction of the complement weight rather than an absolute error on the state, and the retained fraction does not shrink as the state converges. truncrank and truncspace are the strategies with a robust meaning here.

Note

changebonds! is only defined for FiniteMPS, and modifies both the state and its environment.

Fields

• alg_svd::Any: algorithm used for the singular value decomposition

• trunc::MatrixAlgebraKit.TruncationStrategy: truncation strategy selecting how many directions are added to each bond, rather than how much of the bond is kept

See also

Used as the algorithm argument of changebonds and changebonds!.

source

MPSKit.RandExpand Type

struct RandExpand{S} <: MPSKit.Algorithm

An algorithm that expands the bond dimension by adding random unitary vectors that are orthogonal to the existing state. This means that additional directions are added to AL and AR that are contained in the nullspace of both. Note that this happens in parallel, and therefore the expansion will never go beyond the local two-site subspace.

trunc bounds how much is added to each bond, not the total bond dimension that is kept, and it acts on a spectrum that carries no physical information: for an InfiniteMPS the weights are drawn uniformly at random, one per candidate direction, while for a FiniteMPS they are the singular values of a randomized two-site update restricted to the orthogonal complement. Only truncrank and truncspace therefore have a robust meaning — trunctol(; atol = x) keeps the directions whose random weight happens to exceed x. The trunc of SvdCut, and of the drivers DMRG and TDVP, has the other meaning: it bounds what is kept.

Note

The environments are not used here, but changebonds! modifies both the state and environment so they remain consistent.

Fields

• alg_svd::Any: algorithm used for the singular value decomposition

• trunc::MatrixAlgebraKit.TruncationStrategy: truncation strategy selecting how many directions are added to each bond, rather than how much of the bond is kept

See also

Used as the algorithm argument of changebonds and changebonds!.

source

MPSKit.SvdCut Type

struct SvdCut{S} <: MPSKit.Algorithm

An algorithm that uses truncated SVD to change the bond dimension of a state or operator. This is achieved by a sweeping algorithm that locally performs (optimal) truncations in a gauged basis.

changedbonds! is only defined for FiniteMPS and FiniteMPO.

Fields

• alg_svd::Any: algorithm used for the singular value decomposition

• trunc::MatrixAlgebraKit.TruncationStrategy: algorithm used for truncation of the gauge tensors

See also

Used as the algorithm argument of changebonds and changebonds!.

References

• Parker et al. Phys. Rev. B 102 (2020)

source

MPSKit.VUMPSSvdCut Type

struct VUMPSSvdCut <: MPSKit.Algorithm

An algorithm that uses a two-site update step to change the bond dimension of a state.

Note

changebonds! is not defined.

Fields

• alg_gauge::Any: algorithm used for gauging the InfiniteMPS

• alg_eigsolve::Any: algorithm used for the eigenvalue solvers

• alg_svd::Any: algorithm used for the singular value decomposition

• trunc::MatrixAlgebraKit.TruncationStrategy: algorithm used for truncation of the two-site update

See also

Used as the algorithm argument of changebonds.

source

MPSKit.SketchedExpand Type

struct SketchedExpand{S} <: MPSKit.Algorithm

An algorithm that expands the bond dimension like OptimalExpand — selecting the dominant directions of the projected two-site update orthogonal to the current state — but at single-site cost using the randomized "shrewd selection" of Controlled Bond Expansion. A random sketch of the orthogonal complement is folded into the effective environment, collapsing the large bond before the two-site update is ever formed, and the dominant directions are read off a small singular value decomposition.

The state-preserving behaviour matches OptimalExpand.

Note

trunc bounds how much is added to each bond, not the total bond dimension that is kept: it sizes the sketch target Vk within the orthogonal complement (see sketch_space), so truncrank(k) aims to grow every bond by k, capped by the dimension of the local complement. Because that target space is selected from uniformly random weights rather than from a spectrum, its per-sector split is drawn at random rather than ordered by importance — unlike OptimalExpand, where the decomposition itself picks out the dominant sectors — so only truncrank and truncspace have a robust meaning here. The trunc of SvdCut, and of the drivers DMRG and TDVP, has the other meaning: it bounds what is kept.

Note

Only defined for FiniteMPS (through changebond!), so it can be used standalone or as the alg_expand strategy of DMRG. The reported ϵ_2site is a randomized estimate, and the folded application does not exploit JordanMPO sparsity.

Fields

• alg_orth::Any: algorithm used to orthonormalize the sketched complement (passed as the alg of left_orth!/right_orth!); nothing selects QR without oversampling and an SVD-based decomposition otherwise

• trunc::MatrixAlgebraKit.TruncationStrategy: truncation strategy selecting how many directions are added to each bond, rather than how much of the bond is kept

• oversampling::Int64: number of extra sketch columns drawn beyond the target rank (range-finder oversampling)

See also

Used as the algorithm argument of changebonds and changebonds!.

References

• Gleis et al. Phys. Rev. Lett. 130, 246402 (2023)

source

Note

SketchedExpand is experimental: it uses randomized controlled bond expansion (CBE), so its reported error estimate is itself randomized, and it is only defined for FiniteMPS.

Inspecting the virtual spaces

The bond dimension of an MPS or MPO is the dimension of the virtual space living on a given bond. The accessors below return that VectorSpace, whose dim gives the numeric bond dimension.

MPSKit.left_virtualspace Function

left_virtualspace(ψ::AbstractMPS, [pos = 1:length(ψ)])

Return the virtual space of the bond to the left of sites pos.

Warning

In rare cases, the gauge tensor on the virtual space might not be square, and as a result it cannot always be guaranteed that right_virtualspace(ψ, i - 1) == left_virtualspace(ψ, i)

source

MPSKit.right_virtualspace Function

right_virtualspace(ψ::AbstractMPS, [pos = 1:length(ψ)])

Return the virtual space of the bond to the right of site(s) pos.

Warning

In rare cases, the gauge tensor on the virtual space might not be square, and as a result it cannot always be guaranteed that right_virtualspace(ψ, i - 1) == left_virtualspace(ψ, i)

source

MPSKit.physicalspace Function

physicalspace(ψ::AbstractMPS, [pos = 1:length(ψ)])

Return the physical space of the site tensor at site i.

source