Difference between revisions of "Tensor train module"

From Spinach Documentation Wiki
Jump to: navigation, search
(Tensor train functions)
(Polyadic functions)
 
(19 intermediate revisions by 2 users not shown)
Line 5: Line 5:
 
</center>
 
</center>
  
where <math>\mathbf{1}</math> denotes a unit matrix of appropriate dimension and the Pauli matrices <math>\left\{ {{{\hat{\sigma }}}_{\text{X}}},{{{\hat{\sigma }}}_{\text{Y}}},{{{\hat{\sigma }}}_{\text{Z}}} \right\}</math> 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 un-opened.
+
where <math>\mathbf{1}</math> denotes a unit matrix of appropriate dimension and the Pauli matrices <math>\left\{ {{{\hat{\sigma }}}_{\text{X}}},{{{\hat{\sigma }}}_{\text{Y}}},{{{\hat{\sigma }}}_{\text{Z}}} \right\}</math> 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. However, specialist knowledge of numerical linear algebra is required - this is deep water.  
+
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
  
 
==Creating tensor train and polyadic objects==
 
==Creating tensor train and polyadic objects==
Line 96: Line 98:
  
 
[[polyadic/full.m]] - returns the matrix represented by the polyadic as a full matrix.
 
[[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/inflate.m]] - returns the matrix represented by the polyadic as a sparse matrix.
  
 
[[polyadic/isempty.m]] - returns true for polyadics with zero dimensions.
 
[[polyadic/isempty.m]] - returns true for polyadics with zero dimensions.
 
[[polyadic/isfloat.m]] - returns true.
 
 
[[polyadic/ismatrix.m]] - returns true.
 
 
[[polyadic/isnumeric.m]] - returns true.
 
  
 
[[polyadic/kron.m]] - concatenates polyadics, which is equivalent to a Kronecker product.
 
[[polyadic/kron.m]] - concatenates polyadics, which is equivalent to a Kronecker product.
Line 115: Line 113:
 
[[polyadic/nnz.m]] - number of non-zeros in the cores of the polyadic.
 
[[polyadic/nnz.m]] - number of non-zeros in the cores of the polyadic.
  
[[polyadic/numel.m]] - number of elements in the matrix represented by a polyadic.
+
[[polyadic/plus.m]] - buffered addition operation.
 +
 
 +
[[polyadic/prefix.m]] - buffered multiplication operation.
  
[[polyadic/plus.m]] - buffered addition operation.
+
[[polyadic/simplify.m]] - internal structure simplification.
  
 
[[polyadic/size.m]] - size of the matrix represented by the polyadic.
 
[[polyadic/size.m]] - size of the matrix represented by the polyadic.
 +
 +
[[polyadic/suffix.m]] - buffered multiplication operation.
  
 
[[polyadic/transpose.m]] - transpose operation.
 
[[polyadic/transpose.m]] - transpose operation.
  
 
[[polyadic/validate.m]] - polyadic object structure check.
 
[[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/opium.m]] - constructor function
 +
 +
[[opium/kron.m]] - Kronecker product
 +
 +
[[opium/size.m]] - matrix dimension information
 +
 +
[[opium/mtimes.m]] - matrix-vector product
 +
 +
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.1, authors: [[Ilya Kuprov]], [[Dmitry Savostyanov]], [[Sergey Dolgov]]''
+
''Version 2.4, authors: [[Ilya Kuprov]], [[Dmitry Savostyanov]], [[Sergey Dolgov]]''

Latest revision as of 13:49, 25 July 2019

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:

[math]\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}[/math]

where [math]\mathbf{1}[/math] denotes a unit matrix of appropriate dimension and the Pauli matrices [math]\left\{ {{{\hat{\sigma }}}_{\text{X}}},{{{\hat{\sigma }}}_{\text{Y}}},{{{\hat{\sigma }}}_{\text{Z}}} \right\}[/math] 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

Creating tensor train and polyadic objects

The function that creates tensor trains is ttclass.m. Use polyadic.m for polyadics.

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/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.

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/opium.m - constructor function

opium/kron.m - Kronecker product

opium/size.m - matrix dimension information

opium/mtimes.m - matrix-vector product

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