Tensor train module
Kronecker product expressions appear naturally in spin dynamics because the state space of a multi-spin system is a direct product of the state spaces of individual spins. A simple example is provided by Cartesian projection operators:
\(\hat{S}_{\left\{ \text{X,Y,Z} \right\}}^{\left( n \right)}=\mathbf{1}\otimes \mathbf{1}\otimes ...\otimes {{\hat{\sigma }}_{\left\{ \text{X,Y,Z} \right\}}}\otimes ...\otimes \mathbf{1}\otimes \mathbf{1}\)
where \(\mathbf{1}\) denotes a unit matrix of appropriate dimension and the Pauli matrices \(\left\{ {{{\hat{\sigma }}}_{\text{X}}},{{{\hat{\sigma }}}_{\text{Y}}},{{{\hat{\sigma }}}_{\text{Z}}} \right\}\) occur in the n-th position of the direct product sequence. If the Kronecker products are opened, the matrix is huge. But it is often possible to leave them closed.
Although such representations have been known for a long time, they are rather hard to work with. In Spinach, we made an attempt. Two types of unopened Kronecker product formats are supported - tensor trains and polyadics. Both are very space-efficient: enormous matrices can be packed into a few kilobytes.
The details are described in our paper on this subject: http://dx.doi.org/10.1126/sciadv.aaw8962
Contents
Creating tensor train and polyadic objects
The function that creates tensor trains is ttclass.m. Use polyadic.m for polyadics.
polyadic.m - Creates a polyadic object representing a matrix as a sum of unopened Kronecker products, for example a two-term object with cores {A,B,C} and {D,E} represents A(x)B(x)C + D(x)E.
ttclass.m - Creates an object of a tensor train class.
Tensor train functions
ttclass/amensolve.m - solves the linear system Ax=y using the AMEn iteration.
ttclass/amensum.m - tensor train summation without loss of accuracy.
ttclass/clearcoeff.m - absorbs the physical coefficient of the tensor train into its cores.
ttclass/conj.m - element-wise conjugation of a matrix in a TT representation.
ttclass/ctranspose.m - conjugate-transpose of a matrix in a TT representation.
ttclass/diag.m – mimics diag for matrices. If an input is ttclass matrix, returns a ttclass vector (matrix with 1 column) containing the diagonal. If an input is a vector, returns a diagonal matrix.
ttclass/dot.m – mimics the dot product operation for matrices.
ttclass/full.m – mimics the corresponding operation for sparse matrices. Computes all Kronecker products and returns full matrix. May result in out-of-memory errors for large matrices.
ttclass/hdot.m – the Hadamard dot product operation.
ttclass/ismatrix.m - returns true for non-empty TT objects.
ttclass/isnumeric.m - returns true for non-empty TT objects
ttclass/isreal.m - returns true for real-valued ttclass objects.
ttclass/kron.m - Kronecker product of tensor train representation of matrices.
ttclass/mean.m – mimics the corresponding operation for matrices. If the input is a ttclass matrix, returns a vector of its mean values along the specified dimension. If the input is a ttclass vector, returns the mean value in a scalar.
ttclass/minus.m - tensor train subtraction.
ttclass/mldivide.m - matrix left divide for TT objects.
ttclass/mrdivide.m - divides a tensor train by a scalar.
ttclass/mtimes.m - matrix product in the TT representation.
ttclass/nnz.m - number of non-zeros used by the TT object.
ttclass/numel.m - Number of elements in the matrix represented by a tensor train.
ttclass/norm.m – computes a norm of the ttclass object. Because of the internal structure of the tensor train format, only the Frobenius norm can be computed reasonably fast.
ttclass/ttort.m - TT orthogonalisation.
ttclass/pack.m - pack up the additions buffer.
ttclass/plus.m - tensor train addition.
ttclass/rand.m - random tensor trains.
ttclass/ranks.m – returns tensor train ranks of the tensor trains buffered in the ttclass.
ttclass/rdivide.m - divides a tensor train by a scalar.
ttclass/revert.m - computes a bit-revert permutation of a tensor train.
ttclass/shrink.m – compresses a given ttclass object into a single tensor train with optimal ranks.
ttclass/sizes.m – returns mode sizes of a ttclass object (dimensions of elementary matrices).
ttclass/size.m - returns the size of the matrix represented by the tensor train.
ttclass/subsref.m - provides indexing functionality for tensor train objects.
ttclass/sum.m - mimics the corresponding operation for matrices. If the input is a ttclass matrix, returns a vector of its sums along the specified dimension. If an input is a ttclass vector, returns a sum of its values in a scalar.
ttclass/trace.m – returns the trace of a given matrix.
ttclass/transpose.m - transpose of a matrix represented by a tensor train.
ttclass/truncate.m - performs right-to-left SVD recompression for a tensor train.
ttclass/unit_like.m - unit tensor train with the same topology as the one supplied.
ttclass/vec.m – reshapes a ttclass matrix into the ttclass vector with the same elements.
Polyadic functions
polyadic/allfinite.m - true if all numeric data in the polyadic object is finite
polyadic/ctranspose.m - conjugate-transpose operation.
polyadic/full.m - returns the matrix represented by the polyadic as a full matrix.
polyadic/gpuArray.m - uploads the components of the polyadic to GPU.
polyadic/inflate.m - returns the matrix represented by the polyadic as a sparse matrix.
polyadic/isempty.m - returns true for polyadics with zero dimensions.
polyadic/kron.m - concatenates polyadics, which is equivalent to a Kronecker product.
polyadic/minus.m - buffered subtraction operation.
polyadic/mtimes.m - polyadic-times-scalar and polyadic-times-matrix operation.
polyadic/nnz.m - number of non-zeros in the cores of the polyadic.
polyadic/plus.m - buffered addition operation.
polinfo.m - draws an ASCII diagram of a polyadic object.
polyadic/polinfo.m - draws an ASCII diagram of a polyadic object.
polyadic/prefix.m - buffered multiplication operation.
polyadic/simplify.m - internal structure simplification.
polyadic/size.m - size of the matrix represented by the polyadic.
polyadic/suffix.m - buffered multiplication operation.
polyadic/transpose.m - transpose operation.
polyadic/validate.m - polyadic object structure check.
Other overloaded Matlab functions (code inside polyadic.m file) are:
isfloat - always returns true ismatrix - always returns true isnumeric - always returns true numel - number of elements inthe matrix represented by the polyadic
OPIUM object
OPIUM (object pretending it's a unit matrix) is an auxiliary object used by polyadics to avoid explicit storage of unit matrices. It rarely needs to be called directly, but the associated functions are:
opium/full.m - convert into a full matrix
opium/kron.m - Kronecker product
opium/mtimes.m - matrix-vector product
opium/opium.m - constructor function
opium/size.m - matrix dimension information
Other overloaded Matlab functions (code inside opium/opium.m file) are:
nnz - always returns 1 numel - always returns 1 isnumeric - always returns true iseye - returns true for opia with unit coefficients sparse - converts into a sparse matrix conj - complex conjugate ctranspose - conjugate-transpose gpuArray - GPU upload gather - GPU download
Version 2.4, authors: Ilya Kuprov, Dmitry Savostyanov, Sergey Dolgov
