API

A structure representing a Tensor Train (TT) vector.

Fields

• N::Int64: The number of elements in the TT vector.
• ttv_vec::Vector{Array{T,3}}: A vector of 3-dimensional arrays representing the TT cores.
• ttv_dims::NTuple{M,Int64}: A tuple containing the dimensions of the TT vector.
• ttv_rks::Vector{Int64}: A vector containing the TT ranks.
• ttv_ot::Vector{Int64}: A vector containing the orthogonalization information.

Type Parameters

• T<:Number: The type of the elements in the TT vector.

A structure representing a Tensor Train (TT) operator.

Fields

• N::Int64: The number of dimensions of the TT operator.
• tto_vec::Array{Array{T,4},1}: A vector of 4-dimensional arrays representing the TT cores.
• tto_dims::NTuple{M,Int64}: A tuple containing the dimensions of the TT operator.
• tto_rks::Array{Int64,1}: An array containing the TT ranks.
• tto_ot::Array{Int64,1}: An array containing the output dimensions of the TT operator.

tvrks: the TT ranks ``(r0,...,rd)$where$r0=r_d=1``

QTTvector(vec::Vector{<:Array{<:Number, 3}}, rks::Vector{Int64}, ot::Vector{Int64})

Constructs a Quantized Tensor Train (QTT) vector from a given vector of 3-dimensional arrays (cores).

Arguments

• vec::Vector{<:Array{<:Number, 3}}: A vector containing the cores of the QTT vector. Each core must be a 3-dimensional array with the first dimension equal to 2.
• rks::Vector{Int64}: A vector of integer ranks for the QTT vector.
• ot::Vector{Int64}: A vector of integer orthogonalization types for the QTT vector.

Returns

• TTvector{T, N}: A tensor train vector of type T and length N.

Throws

• AssertionError: If any core in vec does not have the first dimension equal to 2.

QTToperator(vec::Vector{Array{T,4}}, rks::Vector{Int64}, ot::Vector{Int64}) where {T}

Constructs a Quantum Tensor Train (QTT) operator from a vector of 4-dimensional arrays (cores).

Arguments

• vec::Vector{Array{T,4}}: A vector containing the cores of the QTT operator. Each core must be a 4-dimensional array with the first two dimensions equal to 2.
• rks::Vector{Int64}: A vector containing the rank sizes of the QTT operator.
• ot::Vector{Int64}: A vector containing the operator types.

Returns

• TToperator{T,N}: A QTT operator constructed from the provided cores, rank sizes, and operator types.

Throws

• AssertionError: If any core in vec does not have the first two dimensions equal to 2.

is_qtt(tt::TTvector) -> Bool

Check if a given TTvector is a QTT (Quantized Tensor Train) vector.

Arguments

• tt::TTvector: The tensor train vector to be checked.

Returns

• Bool: Returns true if all dimensions of the tensor train vector are equal to 2, indicating it is a QTT vector, otherwise returns false.

Example

is_qtt_operator(op::TToperator) -> Bool

Check if a given TToperator is a Quantum Tensor Train (QTT) operator.

Arguments

• op::TToperator: The tensor train operator to be checked.

Returns

• Bool: Returns true if all dimensions of the tensor train operator are equal to 2, indicating it is a QTT operator. Otherwise, returns false.

zeros_tt(dims, rks; ot=zeros(Int64, length(dims)))

Create a tensor train (TT) tensor filled with zeros.

Arguments

• dims::Vector{Int}: A vector specifying the dimensions of the tensor.
• rks::Vector{Int}: A vector specifying the TT-ranks.
• ot::Vector{Int}: (Optional) A vector specifying the output tensor dimensions. Defaults to a vector of zeros with the same length as dims.

Returns

• A TT tensor of type Float64 filled with zeros.

zeros_tt(::Type{T}, dims::NTuple{N,Int64}, rks; ot=zeros(Int64, length(dims)))

Create a TTvector with zero entries.

Arguments

• ::Type{T}: The element type of the TTvector.
• dims::NTuple{N,Int64}: A tuple specifying the dimensions of the TTvector.
• rks: A tuple specifying the TT-ranks.
• ot: An optional argument specifying the orthogonalization tensor. Defaults to a zero vector of the same length as dims.

Returns

• A TTvector{T,N} with zero entries and specified dimensions and ranks.

Throws

• AssertionError if the length of dims plus one is not equal to the length of rks.

ones_tt(dims)

Create a tensor train (TT) format tensor filled with ones.

Arguments

• dims::Tuple: A tuple specifying the dimensions of the tensor.

Returns

• A tensor train (TT) format tensor of the specified dimensions, filled with ones.

ones_tt(::Type{T}, dims) where T

Create a TTvector (Tensor Train vector) with all elements set to one.

Arguments

• ::Type{T}: The data type of the elements in the tensor train.
• dims: A vector specifying the dimensions of the tensor train.

Returns

• A TTvector{T,N} where N is the number of dimensions specified in dims.

Example

ones_tt(n::Integer, d::Integer) -> TensorTrain

Create a tensor train (TT) format tensor filled with ones.

Arguments

• n::Integer: The size of each dimension of the tensor.
• d::Integer: The number of dimensions of the tensor.

Returns

• TensorTrain: A tensor train with each element set to one.

zeros_tto(dims, rks)

Create a tensor train object with all elements initialized to zero.

Arguments

• dims::Vector{Int}: A vector specifying the dimensions of the tensor.
• rks::Vector{Int}: A vector specifying the ranks of the tensor train.

Returns

• A tensor train object with the specified dimensions and ranks, with all elements initialized to zero.

zeros_tto(::Type{T}, dims::NTuple{N,Int64}, rks) where {T,N}

Create a tensor train operator (TTO) with all elements initialized to zero.

Arguments

• ::Type{T}: The type of the elements in the tensor train.
• dims::NTuple{N,Int64}: A tuple containing the dimensions of the tensor train.
• rks: A vector containing the ranks of the tensor train.

Returns

• A TToperator{T,N} object with the specified dimensions and ranks, and all elements initialized to zero.

Throws

• An AssertionError if the length of dims plus one is not equal to the length of rks.

rand_tt(dims, rks; normalise=false, orthogonal=false)

Generate a random Tensor Train (TT) format tensor with specified dimensions and ranks.

Arguments

• dims::Vector{Int}: A vector specifying the dimensions of the tensor.
• rks::Vector{Int}: A vector specifying the TT-ranks.
• normalise::Bool: A keyword argument to indicate whether the tensor should be normalised. Default is false.
• orthogonal::Bool: A keyword argument to indicate whether the tensor should be orthogonal. Default is false.

Returns

• A random tensor in TT format with the specified properties.

rand_tt(::Type{T}, dims, rks; normalise=false, orthogonal=false) where T

Generate a random Tensor Train (TT) tensor with specified dimensions and ranks.

Arguments

• ::Type{T}: The data type of the tensor elements.
• dims: A vector specifying the dimensions of the tensor.
• rks: A vector specifying the TT-ranks.
• normalise: A boolean flag indicating whether to normalize the TT-cores. Default is false.
• orthogonal: A boolean flag indicating whether to orthogonalize the TT-cores. Default is false.

Returns

• A TT tensor with random elements of type T.

rand_tt(dims, rmax::Int; T=Float64, normalise=false, orthogonal=false)

Generate a random Tensor Train (TT) vector with specified dimensions and rank.

Arguments

• dims::Vector{Int}: A vector specifying the dimensions of each mode of the tensor.
• rmax::Int: The maximum TT-rank.
• T::Type (optional): The element type of the tensor (default is Float64).
• normalise::Bool (optional): If true, normalizes each core tensor (default is false).
• orthogonal::Bool (optional): If true, orthogonalizes each core tensor (default is false).

Returns

• TTvector{T,d}: A TTvector object containing the generated TT cores, dimensions, ranks, and a zero vector for the TT ranks.

rand_tt(x_tt::TTvector{T,N}; ε=convert(T,1e-3)) -> 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-3 converted to type T.

Returns

• TTvector{T,N}: A new TT vector with added Gaussian noise.

TT decomposition by the Hierarchical SVD algorithm * 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. The root of the TT decomposition is at index i.e. $A_i$ for $i < index$ are left-orthogonal and $A_i$ for $i > index$ are right-orthogonal. Singular values lower than tol are discarded.

ttv_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.ttv_dims.

Returns the TT decomposition of a matrix using the HSVD algorithm

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 [n_1, ..., n_d, n_1, ..., n_d], where n_i are the dimensions of the TToperator.

rand_tto(dims, rmax::Int; T=Float64)

Generate a random Tensor Train (TT) operator with specified dimensions and maximum rank.

Arguments

• dims::Vector{Int}: A vector specifying the dimensions of the TT operator.
• rmax::Int: The maximum rank for the TT cores.
• T::DataType: The data type of the elements in the TT cores (default is Float64).

Returns

• TToperator{T,d}: A TT operator with random elements.

visualize(tt::TTvector)

Visualizes a Tensor Train (TT) vector by creating a textual representation of its dimensions and ranks.

Arguments

• tt::TTvector: A Tensor Train vector object.

visualize(tt::TToperator)

Visualizes a Tensor Train (TT) operator by creating a textual representation of its dimensions and ranks.

Arguments

• tt::TToperator: A Tensor Train operator object.

tt_svdvals(x_tt::TTvector{T,N}; tol=1e-14) where {T<:Number, N}

Compute the singular values of a Tensor Train (TT) vector x_tt.

Arguments

• x_tt::TTvector{T,N}: The input TT vector.
• tol=1e-14: Tolerance for truncating small singular values. Default is 1e-14.

Returns

• Σ: An array of arrays containing the singular values for each TT core.

tt2qtt(tt_tensor::TToperator{T,N}, row_dims::Vector{Vector{Int}}, col_dims::Vector{Vector{Int}}, threshold::Float64=0.0) where {T<:Number,N}

Convert a TT (Tensor Train) operator to a QTT (Quantized Tensor Train) operator.

Arguments

• tt_tensor::TToperator{T,N}: The input TT operator.
• row_dims::Vector{Vector{Int}}: A vector of vectors specifying the row dimensions for each core.
• col_dims::Vector{Vector{Int}}: A vector of vectors specifying the column dimensions for each core.
• threshold::Float64=0.0: A threshold for rank reduction during SVD. Default is 0.0, meaning no rank reduction.

Returns

• qtt_tensor::TToperator{T,M}: The resulting QTT operator.

Details

This function converts a given TT operator into a QTT operator by splitting each core of the TT operator according to the specified row and column dimensions. It performs SVD on reshaped cores and applies rank reduction based on the given threshold. The resulting QTT cores are then used to construct the QTT operator.

tt2qtt(tt_tensor::TTvector{T,N}, dims::Vector{Vector{Int}}, threshold::Float64=0.0) where {T<:Number,N}

Convert a Tensor Train (TT) tensor to a Quantized Tensor Train (QTT) tensor.

Arguments

• tt_tensor::TTvector{T,N}: The input TT tensor to be converted.
• dims::Vector{Vector{Int}}: A vector of vectors specifying the dimensions for each core in the QTT tensor.
• threshold::Float64=0.0: A threshold for rank reduction during the SVD step. Default is 0.0, meaning no rank reduction.

Returns

• qtt_tensor::TTvector{T,M}: The resulting QTT tensor.

Description

This function converts a given TT tensor into a QTT tensor by splitting each core of the TT tensor according to the specified dimensions. It performs Singular Value Decomposition (SVD) on reshaped cores and applies rank reduction based on the given threshold. The resulting QTT cores are then assembled into a new QTT tensor.

matricize(tt::TToperator{T, M}) where {T, M}

Convert a tensor train operator (TToperator) into its matrix form.

Arguments

• tt::TToperator{T, M}: The tensor train operator to be matricized.

Returns

• A matrix representation of the tensor train operator.

Description

The function takes a tensor train operator and converts it into a matrix by reshaping and permuting its cores. It starts with the first core and iteratively processes each subsequent core, updating the matrix representation at each step. If the size of the first core does not match the expected dimensions, an error is thrown.

matricize(tt::TTvector{T, M}) where {T, M}

Convert a Tensor Train (TT) vector into a matrix form.

Arguments

• tt::TTvector{T, M}: A Tensor Train vector of type T and order M.

Returns

• A matrix representation of the input Tensor Train vector.

Description

The function takes the first core of the Tensor Train vector and reshapes it into a matrix. It then iteratively processes each subsequent core, performing tensor contractions and reshaping operations to build the final matrix representation.

Errors

• Throws an error if the size of the first core does not match the expected dimensions.

matricize(qtt::TToperator{Float64}, core::Int)::Vector{Float64}

Convert a TToperator to a vector of Float64 values by extracting a specific core.

Arguments

• qtt::TToperator{Float64}: The TToperator to be converted.
• core::Int: The core index to be used for the conversion.

Returns

• Vector{Float64}: A vector of Float64 values representing the specified core of the TToperator.

Description

This function converts a given TToperator into a vector of Float64 values by extracting the specified core. It first converts the TToperator to a full tensor using tto_to_tensor, then calculates the dyadic points and binary indices to extract the values from the tensor.

matricize(qtt::TTvector{Float64}, core::Int)::Vector{Float64}

Convert a TTvector to a vector of Float64 values by extracting a specific core.

Arguments

• qtt::TTvector{Float64}: The TTvector to be converted.
• core::Int: The core index to be used for the conversion.

Returns

• Vector{Float64}: A vector of Float64 values representing the specified core of the TTvector.

Description

This function converts a given TTvector into a vector of Float64 values by extracting the specified core. It first converts the TTvector to a full tensor using ttv_to_tensor, then calculates the dyadic points and binary indices to extract the values from the tensor.

concatenate(tt1::TTvector, tt2::TTvector) -> TTvector

Concatenates two TTvector objects tt1 and tt2 into a single TTvector.

Arguments

• tt1::TTvector: The first TTvector to concatenate.
• tt2::TTvector: The second TTvector to concatenate.

Returns

• TTvector: A new TTvector that is the result of concatenating tt1 and tt2.

Throws

• ArgumentError: If the final rank of tt1 does not equal the initial rank of tt2.

concatenate(tt1::TToperator, tt2::TToperator) -> TToperator

Concatenates two TToperators tt1 and tt2 into a single TToperator.

Arguments

• tt1::TToperator: The first TToperator.
• tt2::TToperator: The second TToperator.

Returns

• TToperator: A new TToperator that is the concatenation of tt1 and tt2.

Throws

• ArgumentError: If the final rank of tt1 does not equal the initial rank of tt2.

Description

This function concatenates two TToperators by combining their tensor train vectors, dimensions, ranks, and operator types. The resulting TToperator has the combined properties of the input TToperators.

concatenate(tt::TTvector{T, N}, other::Union{TTvector{T}, Vector{Array{T, 3}}}, overwrite::Bool=false) where {T, N}

Concatenates a TTvector with another TTvector or a vector of 3-dimensional arrays.

Arguments

• tt::TTvector{T, N}: The original TTvector to be concatenated.
• other::Union{TTvector{T}, Vector{Array{T, 3}}}: The TTvector or vector of 3-dimensional arrays to concatenate with tt.
• overwrite::Bool=false: If true, the original tt is modified in place. Otherwise, a copy of tt is made before concatenation.

Returns

• TTvector{T, N_new}: A new TTvector with concatenated cores, updated dimensions, ranks, and orthogonality indicators.

Throws

• DimensionMismatch: If the ranks or dimensions of tt and other do not match.
• ArgumentError: If other is not of type TTvector or Vector{Array{T, 3}}.

1d-discrete Laplacian

1D Discrete Laplacian for Neumann-Neumann (NN) Boundary Conditions

1D Discrete Laplacian for Dirichlet-Neumann (DN) Boundary Conditions

1D Discrete Laplacian for Neumann-Dirichlet (ND) Boundary Conditions

1D Discrete Laplacian for Periodic Boundary Conditions

n^d Discrete Laplacian in TTO format or 1D Laplacian if d=1.

Constructs the QTT representation of a tridiagonal Toeplitz matrix with parameters α (main diagonal), β (upper diagonal), γ (lower diagonal) for size 2^l x 2^l.

n^d discrete shift in TTO format with rank 2 of S = s ⊗ id ⊗ … ⊗ id + ⋯ + id ⊗ … ⊗ id ⊗ s

1D Discrete Gradient Operator for Dirichlet-Dirichlet (DD) Boundary Conditions

n^d Discrete Gradient in TTO format or 1D Gradient if d=1.

Jacobian_tto(n::Int, d::Int, ∇_func::Function) -> TToperator{Float64, d}

Constructs a tensor train (TT) representation of the Jacobian operator

Arguments

• n::Int: The size of each dimension in the tensor.
• d::Int: The number of dimensions.
• ∇_func::Function: boundary TToperator.

Returns

• TToperator{Float64, d}: A tensor train operator representing the Jacobian.

Description

This function generates the gradient operators for each dimension and adjusts the rank structure to accommodate all gradients. It constructs the tensor train cores for the first, middle, and last dimensions, and combines them into a TToperator.