Core types and operations

TTVector{T<:Number, M}

A tensor in tensor-train (TT) format, also called a matrix product state:

x[i₁, …, i_M] = G₁[i₁, :, :] * G₂[i₂, :, :] * ⋯ * G_M[i_M, :, :]

where core Gₖ has size (nₖ, rₖ₋₁, rₖ) and r₀ = r_M = 1.

Fields

• cores::Vector{Array{T,3}}: the cores, each of size (dims[k], ranks[k], ranks[k+1]).
• dims::NTuple{M,Int64}: physical dimensions (n₁, …, n_M).
• ranks::Vector{Int64}: TT ranks (r₀, r₁, …, r_M), of length M + 1.
• orthogonality::Vector{Int64}: the interval [left, right], with 1 ≤ left ≤ right ≤ M. The cores k < left are left-orthogonal and the cores k > right are right-orthogonal; nothing is recorded about the cores inside the interval. [c, c] is an orthogonality center at core c, and [1, M] records nothing.

The fields cannot be reassigned, but in-place operations such as tt_round! and add! replace the contents of cores, ranks, and orthogonality; any other object built on the same vectors (such as a QTTVector wrapping this TTVector) sees the change.

The number of cores (sites) is the type parameter M, returned by nsites(x).

Constructor

TTVector{T, M}(cores, dims, ranks; orthogonality = (1, M))

A Vector{Int64} passed as orthogonality is stored without copying. The constructor checks the orthogonality interval but not that the cores, dims, and ranks are consistent with each other or that the cores have the recorded orthogonality. Use constructors such as tt_decomp, rand_tt, or zeros_tt to build valid instances.

TTOperator{T<:Number, M}

A linear operator in tensor-train format, also called a matrix product operator:

A[(i₁, …, i_M), (j₁, …, j_M)] = A₁[i₁, j₁, :, :] * ⋯ * A_M[i_M, j_M, :, :]

where core Aₖ has size (mₖ, nₖ, rₖ₋₁, rₖ) (output index, input index, left rank, right rank) and r₀ = r_M = 1.

Fields

• cores::Vector{Array{T,4}}: the cores, each of size (row_dims[k], col_dims[k], ranks[k], ranks[k+1]).
• row_dims::NTuple{M,Int64}: output (row) dimensions (m₁, …, m_M).
• col_dims::NTuple{M,Int64}: input (column) dimensions (n₁, …, n_M).
• ranks::Vector{Int64}: TT ranks (r₀, r₁, …, r_M), of length M + 1.
• orthogonality::Vector{Int64}: the orthogonality interval [left, right], with the same meaning as for TTVector.

The number of cores (sites) is the type parameter M, returned by nsites(A).

Constructor

TTOperator{T, M}(cores, row_dims, col_dims, ranks; orthogonality = (1, M))
TTOperator{T, M}(cores, dims, ranks; orthogonality = (1, M))

The second form builds a square operator with row_dims == col_dims == dims. A Vector{Int64} passed as orthogonality is stored without copying. The constructor checks the orthogonality interval but not that the other fields are consistent with each other.

AbstractTTVector{T, M}

Supertype of tensor-train vectors with element type T and M sites: TTVector and the QTT wrapper QTTVector.

AbstractTTOperator{T, M}

Supertype of tensor-train operators with element type T and M sites: TTOperator and the QTT wrapper QTTOperator.

A Quantized Tensor Train vector with explicit multi-dimensional ordering metadata.

Identical TT fields as TTVector plus:

• n_dims: number of spatial dimensions
• bits_per_dim: bits per dimension (total sites = ndims × bitsper_dim)
• ordering: :interleaved or :serial

A Quantized Tensor Train operator with explicit multi-dimensional ordering metadata.

tt_decomp(tensor::Array; center=1, tol=1e-12) -> TTVector

Decompose a dense tensor into a TTVector with the TT-SVD (hierarchical SVD) algorithm of Oseledets (2011); see also Schollwöck (2011).

The cores k < center are left-orthogonal, the cores k > center are right-orthogonal, and core center carries the norm. At every SVD, singular values smaller than tol are discarded; tol is an absolute threshold, not relative to the norm of tensor.

• Oseledets, I. V. (2011). Tensor-train decomposition. SIAM Journal on Scientific Computing, 33(5), 2295-2317.
• Schollwöck, U. (2011). The density-matrix renormalization group in the age of matrix product states. Annals of Physics, 326(1), 96-192.

tto_decomp(tensor::Array; center=1) -> TTOperator

Decompose a dense operator into a TTOperator with the TT-SVD algorithm. tensor has 2d indices ordered [i₁, …, i_d, j₁, …, j_d] (output indices first, then input indices). The center pairs are interleaved to [(i₁, j₁), …, (i_d, j_d)] and decomposed with tt_decomp using its default tolerance.

tt_to_tensor(x_tt::TTVector{T,N}) where {T<:Number, N}

Convert a TTVector (Tensor Train vector) to a full tensor.

Arguments

• x_tt::TTVector{T,N}: The input TTVector to be converted. T is the element type, and N is the number of dimensions.

Returns

• A tensor of type Array{T,N} with the same dimensions as specified in x_tt.dims.

tto_to_tensor(tto::TTOperator{T,N}) where {T<:Number, N}

Convert a TTOperator to a full tensor.

Arguments

• tto::TTOperator{T,N}: The TTOperator to be converted, where T is a subtype of Number and N is the order of the tensor.

Returns

• A tensor of type Array{T, 2N} with dimensions [m_1, ..., m_d, n_1, ..., n_d], where m_i are the row dimensions and n_i the column dimensions of the TTOperator.

tto_to_tt(A::TTOperator{T,N}) where {T<:Number,N}

Convert a TTOperator to a TTVector.

Arguments

• A::TTOperator{T,N}: The TTOperator to be converted. T is the element type, and N is the number of dimensions.

Returns

• TTVector{T,N}: The resulting TTVector.

Details

This function takes a TTOperator and converts it into a TTVector. It reshapes the cores of the TTOperator and constructs a TTVector with the appropriate dimensions and ranks. The result owns its cores, ranks, and orthogonality interval; mutating it does not change A.

rand_tt([T=Float64,] dims, ranks; normalize=false, orthogonal=false)
rand_tt(dims, max_bond::Int; normalize=false, orthogonal=false)

Generate a random TTVector with element type T, physical dimensions dims, and TT ranks ranks (a vector of length length(dims) + 1 with ranks[1] == ranks[end] == 1). Core entries are drawn from randn.

With an integer max_bond, every interior rank is set to max_bond, reduced where the dimensions force a smaller rank (see admissible_ranks).

Keyword arguments

• normalize::Bool=false: scale core k by 1/√(dims[k]·ranks[k+1]).
• orthogonal::Bool=false: when normalize is also true, replace every core by a right-orthogonal core from a QR factorization. Has no effect otherwise.

rand_tt(x_tt::TTVector{T,N}; ε=convert(T,1e-5)) -> TTVector{T,N}

Generate a random tensor train (TT) vector by adding Gaussian noise to the input TT vector x_tt.

Arguments

• x_tt::TTVector{T,N}: The input TT vector to which noise will be added.
• ε: The standard deviation of the Gaussian noise to be added. Default is 1e-5 converted to type T.

Returns

• TTVector{T,N}: A new TT vector with added Gaussian noise and independent mutable storage.

rand_tto(dims, max_bond::Int; T=Float64) -> TTOperator

Return a random TTOperator with physical dimensions dims and entries drawn from randn. Every interior rank is max_bond, reduced where the dimensions force a smaller rank.

zeros_tt([T=Float64,] dims, ranks; orthogonality=(1, length(dims))) -> TTVector
zeros_tt(n::Integer, d::Integer, r; orthogonality=(1, d), admissible=true) -> TTVector

Return a TTVector with element type T, physical dimensions dims, TT ranks ranks (length length(dims) + 1), and all cores zero. orthogonality sets the orthogonality interval (left, right) recorded on the result.

The second form uses d sites of dimension n and interior ranks r. With admissible = true, ranks are reduced where the dimensions force a smaller rank (see admissible_ranks); otherwise every interior rank is r.

zeros_tto([T=Float64,] dims, ranks) -> TTOperator
zeros_tto(T, row_dims, col_dims, ranks) -> TTOperator
zeros_tto(n, d, r) -> TTOperator

Return a TTOperator with element type T, TT ranks ranks, and all cores zero. The first form is square with physical dimensions dims; the second takes row and column dimensions separately. The third form uses d sites of dimension n and interior ranks r, reduced where the dimensions force a smaller rank.

id_tto(d; n_dim=2)

Create an identity tensor train operator (TTO) of dimension d with optional keyword argument n_dim specifying the number of dimensions (default is 2).

Arguments

• d::Int: The dimension of the identity tensor train operator.
• n_dim::Int: The number of dimensions of the identity tensor train operator (default is 2).

Returns

• An identity tensor train operator of the specified dimension and number of dimensions.

admissible_ranks(ranks, dims; max_bond=1024)

Return a copy of ranks in which every rank is reduced to the largest value a tensor train with physical dimensions dims can have at that bond, and to at most max_bond.

ranks has length length(dims) + 1. Rank i is capped by the product of the dimensions to its left and by the product of the dimensions to its right; the boundary ranks are 1.

concatenate(tt1::TTVector, tt2::TTVector) -> TTVector
concatenate(A1::TTOperator, A2::TTOperator) -> TTOperator

Join two tensor trains into one with nsites(tt1) + nsites(tt2) cores: the cores of tt1 followed by the cores of tt2. The last rank of the first argument must equal the first rank of the second; for standard boundary ranks of 1 the result represents the tensor (Kronecker) product.

nsites(x::Union{AbstractTTVector, AbstractTTOperator}) -> Int

Number of cores (sites) of the tensor train x.

Base.copy(x_tt::TTVector{T,N}) where {T<:Number,N}

Create a deep copy of a TTVector object.

Arguments

• x_tt::TTVector{T,N}: The TTVector object to be copied, where T is a subtype of Number and N is the dimensionality.

Returns

• A new TTVector object that is a deep copy of x_tt.

Adds two TTVectors and returns a new TTVector.

Adds two TTOperators and returns a new TTOperator.

Multiplies a TTVector by a scalar and returns a new TTVector.

Multiplies a TTOperator by a scalar and returns a new TTOperator.

Contracts the TTOperator A with the TTVector x.

Contracts a rectangular TTOperator with one additional output site against a TTVector.

Multiplies two TTOperators and returns a new TTOperator.

adjoint(A::TTOperator) -> TTOperator
A'

Conjugate transpose of A: every core has its output and input indices swapped and its entries conjugated. The ranks are unchanged.

add!(x::TTVector, y::TTVector) -> x

Overwrite x with x + y. The ranks of the result are the sums of the ranks of x and y; no truncation is performed (see tt_round!).

Computes the dot product of two TTVectors and returns a scalar.

Computes the norm of a TTVector.

Computes the Hadamard product (element-wise multiplication) of two TTVectors and returns a new TTVector.

x ⊕ y

Elementwise (Hadamard) product of two TTVectors; identical to hadamard.

hadamard_ttm(x::TTVector, y::TTVector; trunc_tol=1e-14, max_bond=typemax(Int)) -> TTVector

Elementwise (Hadamard) product of x and y by tensor train multiplication (Michailidis, Fenton & Kiffner, arXiv:2410.19747). The cores of x followed by the reversed cores of y form a chain of 2d cores. The cores of y are moved through the chain by swaps of adjacent cores until each meets the core of x with the same physical index, and the two are then merged. Each swap is a truncated SVD, so the full product with ranks rˣ·rʸ is never formed.

The chain is kept in mixed canonical form with its orthogonality center on the pair being swapped, which makes each truncation optimal for the whole chain. trunc_tol and max_bond are applied to every swap with the rule of tt_round!, relative to the norm of the chain. That norm is at most ‖x‖·‖y‖, so the error of the result is of the order of trunc_tol·‖x‖·‖y‖, which can exceed trunc_tol·‖x∘y‖.

max_bond limits every bond of the intermediate chain, and those can need a larger rank than the bonds of the product. A cap that the product itself would fit under can therefore still cause an error; hadamard followed by tt_round! truncates the product only.

The result has its orthogonality center on the first core.

outer_product(x::TTVector, y::TTVector) -> TTOperator

Return the rank-one operator x y† as a TTOperator, with entries x[i] * conj(y[j]). Its TT ranks are the products of the ranks of x and y.

Computes the Kronecker product of two TTOperators and returns a new TTOperator.

Computes the Kronecker product of two TTVectors and returns a new TTVector.

A ⊗ B

Kronecker product of two TTOperators or two TTVectors; identical to kron. The result has the cores of A followed by the cores of B.

⨝(A::TTOperator, B::TTOperator)
A ⨝ B

Inner core product of two TT operators (the ⋈ of the QTT literature; Julia's parser rejects U+22C8, so the visually identical U+2A1D ⨝ is used). At each site the physical TT blocks are combined by a tensor (Kronecker) product, growing the physical dimension from dᴬ to dᴬ·dᴮ, while the bond indices combine multiplicatively:

(A ⨝ B)ₖ[(iᴬiᴮ), (jᴬjᴮ), (aᴬaᴮ), (bᴬbᴮ)] = Aₖ[iᴬ,jᴬ,aᴬ,bᴬ] · Bₖ[iᴮ,jᴮ,aᴮ,bᴮ].

The result is an operator on the tensor-product physical space, interleaving the two operators site-by-site, with ranks A.ranks .* B.ranks. For separable (rank-1) operators this is exactly the textbook inner core product; in general it is its rank-stable extension to arbitrary TT operators. Unlike kron, which concatenates the cores of the two operators (sequential bit ordering), ⨝ keeps the same number of sites and interleaves them — usually the lower-rank ordering for multivariate operators.

The dual operation — physical blocks composed by matrix product, bonds tensored (the outer core product •) — is ordinary operator multiplication A * B.

∙(A::TTOperator, B::TTOperator)
A ∙ B

Outer core product of two TT operators. The physical TT blocks are composed by matrix product while the bond indices are tensored — i.e. ordinary operator composition, with ranks combining as A.ranks .* B.ranks.

Creates a diagonal TTOperator from a TTVector.

euclidean_distance(a::TTVector, b::TTVector) -> Real

Return ‖a − b‖, computed from the inner products as √(⟨a,a⟩ − 2 Re⟨b,a⟩ + ⟨b,b⟩) (clamped at zero) without forming a − b. Because of cancellation, distances below about √eps · max(‖a‖, ‖b‖) are not resolved; use norm(a - b) when small differences matter.

euclidean_distance_normalized(a::TTVector, b::TTVector)

Return the relative distance ‖a − b‖ / ‖b‖, computed from inner products as √(1 + ⟨a,a⟩/⟨b,b⟩ − 2 Re⟨b,a⟩/⟨b,b⟩). For complex element types the result is a complex number. The same cancellation limit as euclidean_distance applies.

orthogonalize(x::AbstractTTVector; center=1)

Return a tensor train equal to x whose cores left of center are left-orthogonal and whose cores right of center are right-orthogonal, so that core center is the orthogonality center. The cores are computed with QR and LQ factorizations, and the ranks are reduced where the dimensions force a smaller rank.

tt_round!(x::TTVector; trunc_tol=0.0, max_bond=typemax(Int))

Truncate the TT ranks of x in place with the TT-rounding algorithm of Oseledets (2011): one right-to-left orthogonalization sweep followed by one left-to-right truncating SVD sweep, O(d·n·r³) in total.

trunc_tol is a relative Frobenius tolerance for the whole tensor: each of the d − 1 bonds discards a singular-value tail of norm at most trunc_tol·‖x‖/√(d−1), so ‖x − round(x)‖ ≤ trunc_tol·‖x‖. max_bond additionally caps every bond dimension. The result is left-canonical with the orthogonality center on the last core.

tt_round!(A::TTOperator; trunc_tol=0.0, max_bond=typemax(Int))

Truncate the TT ranks of the operator A in place. Rounding is performed on the vectorized operator (tto_to_tt) with the Frobenius norm, so trunc_tol and max_bond have the same meaning as in tt_round! for a TTVector.

tt_round(x::TTVector; trunc_tol=0.0, max_bond=typemax(Int))

Non-mutating variant of tt_round!.

tt_round(A::TTOperator; trunc_tol=0.0, max_bond=typemax(Int))

Non-mutating variant of tt_round! for operators.

tt_compress!(ψ::TTVector, max_bond::Int; trunc_tol=0.0, sweeps=1, verbosity=1)

Compress ψ in place to bond dimension at most max_bond with TT rounding (see tt_round!); trunc_tol has the same meaning as there. A single sweep already gives the quasi-optimal rounding; sweeps > 1 repeats the pass. verbosity ≥ 2 logs one line per pass.

entanglement_entropy(ψ::TTVector; base=exp(1.0))

Compute the von Neumann entanglement entropy across every bond of an MPS.

The returned vector has length nsites(ψ) - 1; entry k is the entropy of the bipartition 1:k | k+1:N. The input state is not mutated. Use base = 2 to return entropy in bits.

visualize(tt)

Print an ASCII bond diagram of the TT structure to stdout.

to_ttvector(tt::TensorCrossInterpolation.TensorTrain) -> TTVector

Convert a tensor train from TensorCrossInterpolation.jl to a TTVector. Defined in the extension that loads when InterpolativeQTT.jl and TensorCrossInterpolation.jl are loaded.

ttvector_manifold(x::TTVector)

Return a ManifoldsBase.jl manifold whose points are TTVectors with the physical dimensions of x, for use with Manopt.jl solvers. The space is flat: the inner product is real(dot(X, Y)), and the retraction is orthogonalize(p + t X), which does not truncate ranks.

Defined in the extension that loads when ManifoldsBase.jl and Manopt.jl are loaded; real element types only.