Welcome to TensorToolbox’s documentation!

Contents:

@author: Daniele Bigoni (dabi@imm.dtu.dk)

@version: 0.1.3

TensorToolbox is the collection of tools for Tensor decomposition and arithmetic

@copyright: 2014 The Technical University of Denmark

TensorToolbox.core.mpi_map(func_code, x, params, procs)

This function applies the function in func_code to the x inputs on procs processors.

Parameters:
  • func_code (str) – String containing the marshalled version of the function
  • x (list) – list of inputs to be passed (pickable)
  • params – parameters to be passed to the function (pickable)
  • procs (int) – number of processors to be used
TensorToolbox.core.idxunfold(dlist, idxs)

Find the index corresponding to the unfolded (flat) version of a tensor

Parameters:
  • dlist (list,int) – list of integers containing the dimensions of the tensor
  • idxs (list,int) – tensor index
Returns:

index for the flatten tensor

TensorToolbox.core.idxfold(dlist, idx)

Find the index corresponding to the folded version of a tensor from the flatten version

Parameters:
  • dlist (list,int) – list of integers containing the dimensions of the tensor
  • idx (int) – tensor flatten index
Returns:

list of int – the index for the folded version

Note:

this routine can be used to get the indexes of a TTmat from indices of a matkron (matrix obtained using np.kron): (i,j) in N^d x N^d -> ((i_1,..,i_d),(j_1,..,j_d)) in (N x .. x N) x (N x .. x N)

TensorToolbox.core.matkron_to_mattensor(A, nrows, ncols)

This function reshapes a 2D-matrix obtained as kron product of len(nrows)==len(ncols) matrices, to a len(nrows)-tensor that can be used as input for the TTmat constructor. Applies the Van Loan-Pitsianis reordering of the matrix elements.

Parameters:
  • A (ndarray) – 2-dimensional matrix
  • nrows,ncols (list,int) – number of rows and number of columns of the original matrices used for the kron product
TensorToolbox.core.mat_to_tt_idxs(rowidxs, colidxs, nrows, ncols)

Mapping from the multidimensional matrix indexing to the tt matrix indexing

(rowidxs,colidxs) = ((i_1,...,i_d),(j_1,...,j_d)) -> (l_1,...,l_d)

Parameters:
  • rowidxs,colidxs (tuple,int) – list of row and column indicies. len(rowidxs) == len(colidxs)
  • nrows,ncols (tuple,int) – dimensions of matrices
Returns:

tuple,int indices in the tt format

TensorToolbox.core.tt_to_mat_idxs(idxs, nrows, ncols)

Mapping from the tt matrix indexing to the multidimensional matrix indexing

(l_1,...,l_d) -> (rowidxs,colidxs) = ((i_1,...,i_d),(j_1,...,j_d))
Parameters:
  • idxs (tuple,int) – list of tt indicies. len(idxs) == len(nrows) == len(ncols)
  • nrows,ncols (tuple,int) – dimensions of matrices
Returns:

(rowidxs,colidxs) = ((i_1,..,i_d),(j_1,..,j_d)) indices in the matrix indexing

TensorToolbox.core.maxvol(A, delta=0.01, maxit=100)

Find the rxr submatrix of maximal volume in A(nxr), n>=r

Parameters:
  • A (ndarray) – two dimensional array with (n,r)=shape(A) where r<=n
  • delta (float) – stopping cirterion [default=1e-2]
  • maxit (int) – maximum number of iterations [default=100]
Returns:

(I,AsqInv,it) where I is the list or rows of A forming the matrix with maximal volume, AsqInv is the inverse of the matrix with maximal volume and it is the number of iterations to convergence

Raises:

raise exception if the dimension of A is r>n or if A is singular

Raises:

ConvergenceError if convergence is not reached in maxit iterations

TensorToolbox.core.lowrankapprox(A, r, Jinit=None, delta=1e-05, maxit=100, maxvoleps=0.01, maxvolit=100)

Given a matrix A nxm, find the maximum volume submatrix with rank r<n,m.

Parameters:
  • A (ndarray) – two dimensional array with dimension nxm
  • r (int) – rank of the maxvol submatrix
  • Jinit (list) – list of integers containing the r starting columns. If None then pick them randomly.
  • delta (float) – accuracy parameter
  • maxit (int) – maximum number of iterations in the lowrankapprox routine
  • maxvoleps (float) – accuracy parameter for each usage of the maxvol algorithm
Parma int maxvolit:
 

maximum number of iterations in the maxvol routine

Returns:

(I,J,AsqInv,it) where I and J are the list of rows and columns of A that compose the submatrix of maximal volume, AsqInv is the inverse of such matrix and it is the number of iteration to convergence

TensorToolbox.core.ttcross_store(path, TW, TTapp)

Used to store the computed values of a TTcross approximation. Usually needed when the single function evaluation is demanding or when we need to restart TTcross later on.

Parameters:
  • path (string) – path pointing to the location where to store the data
  • TW (TensorWrapper) – Tensor wrapper used to build the ttcross approximation. TW.get_data(), TW.get_X() and TW.get_params() will be stored.
  • TTapp (TTvec) – TTcross approximation. TTapp.ttcross.Jinit will be stored.
TensorToolbox.core.object_store(path, obj)

Used to store any object in the library.

Parameters:
  • path (string) – path pointing to the location where to store the data
  • obj (object) – a pickleable object
class TensorToolbox.core.TensorWrapper(f, X, params=None, twtype='array', data=None, dtype=<type 'object'>, store_file='', store_object=None, empty=False, maxprocs=None, marshall_f=True)

A tensor wrapper is a data structure W that given a multi-dimensional scalar function f(X,params), and a set of coordinates {{x1}_i1,{x2}_i2,..,{xd}_id} indexed by the multi index {i1,..,id}, let you access f(x1_i1,..,xd_id) by W[i1,..,id]. The function evaluations are performed “as needed” and stored for future accesses.

Parameters:
  • f – multi-dimensional scalar function of type f(x,params), x being a list.
  • X (list) – list of arrays with coordinates for each dimension
  • params (tuple) – parameters to be passed to function f
  • twtype (string) – ‘array’ values are stored whenever computed, ‘view’ values are never stored and function f is always called
  • data (dict) – initialization data of the Tensor Wrapper (already computed entries)
  • range_shape (int) – specify the shape of the objects in the tensor wrapper
  • empty (bool) – Creates an instance without initializing it. All the content can be initialized using the setstate() function.
  • maxprocs (int) – Number of processors to be used in the function evaluation (MPI)
dtype

alias of object

get_ndim()

Always returns the number of dimensions of the original tensor

get_shape()

Always returns the shape of the of the original tensor

class TensorToolbox.core.TTvec(A, eps=1e-10, method='svd', lr_r=None, lr_fix_rank=False, lr_Jinit=None, lr_delta=0.0001, lr_maxit=100, mv_eps=1e-06, mv_maxit=100, lr_store_location='', store_object=None, store_freq=1, generate=True)

Constructor of multidimensional tensor in Tensor Train format

Parameters:
  • A (Candecomp,ndarray,TT) – Available input formats are Candecomp, full tensor in numpy.ndarray, Tensor Train structure (list of cores)
  • generate (bool) – whether to perform the construction or just initialize the object
  • method (string) – ‘svd’ use singular value decomposition to construct the TT representation, ‘ttcross’ use low rank skeleton approximation to construct the TT representation.
  • eps (float) – [default == 1e-10] For method==’svd’: precision with which to approximate the input tensor. For method==’ttcross’: TT-rounding tolerance for rank-check.
  • lr_r (list) – list of integer ranks of different cores. If None then the incremental TTcross approach will be used. (method==’ttcross’)
  • lr_fix_rank (bool) – determines whether the rank is allowed to be increased (method==’ttcross’)
  • lr_Jinit (list) – list of list of integers containing the r starting columns in the lowrankapprox routine for each core. If None then pick them randomly. (method==’ttcross’)
  • lr_delta (float) – accuracy parameter in the TT-cross routine (method==’ttcross’). It is the relative error in Frobenious norm between two successive iterations.
  • lr_maxit (int) – maximum number of iterations in the lowrankapprox routine (method==’ttcross’)
  • mv_eps (float) – accuracy parameter for each usage of the maxvol algorithm (method==’ttcross’)
  • mv_maxit (int) – maximum number of iterations in the maxvol routine (method==’ttcross’)
  • fix_rank (bool) – Whether the rank is allowed to increase
  • lr_store_location (string) – Store computed values during construction on the specified file path. The stored values are ttcross_Jinit and the values used in the TensorWrapper. This permits a restart from already computed values. If empty string nothing is done. (method==’ttcross’)
  • store_object (string) – Object to be stored (default are the tensor wrapper and ttcross_Jinit)
  • store_freq (int) – storage frequency. store_freq==1 stores intermediate values at every iteration. The program stores data every store_freq internal iterations. If store_object is a SpectralTensorTrain, then store_freq determines the number of seconds every which to store values.
__getitem__(idxs)
interpolate(Ms=None, eps=1e-08, is_sparse=None)

Interpolates the values of the TTvec at arbitrary points, using the interpolation matrices ``Ms’‘.

Parameters:
  • Ms (list) – list of interpolation matrices for each dimension. Ms[i].shape[1] == self.shape()[i]
  • eps (float) – tolerance with which to perform the rounding after interpolation
  • is_sparse (list) – is_sparse[i] is a bool indicating whether Ms[i] is sparse or not. If ‘None’ all matrices are non sparse
Returns:

TTvec interpolation

Return type:

TTvec

>>> from DABISpectralToolbox import DABISpectral1D as S1D
>>> Ms = [ S1D.LinearInterpolationMatrix(X[i],XI[i]) for i in range(d) ]
>>> is_sparse = [True]*d
>>> TTapproxI = TTapprox.interpolate(Ms,eps=1e-8,is_sparse=is_sparse)
outer_ttcross(eps, lr_r, lr_Jinit, lr_delta, lr_maxit, mv_eps, mv_maxit, fix_rank=False, lr_store_location='', store_object=None, store_freq=1, multidim_point=None)

Construct a TT representation of A using TT cross. This routine manage the outer loops for incremental ttcross or passes everything to ttcross if lr_r are specified.

Parameters:
  • eps (float) – tolerance with which to perform the TT-rounding and check the rank accuracy
  • lr_r (list) – list of upper ranks (A.ndim)
  • lr_Jinit (list) – list (A.ndim-1) of lists of init indices
  • lr_delta (float) – TT-cross accuracy
  • lr_maxit (int) – maximum number of iterations for ttcross
  • mv_eps (float) – MaxVol accuracy
  • mv_maxit (int) – maximum number of iterations for MaxVol
  • fix_rank (bool) – Whether the rank is allowed to increase
  • lr_store_location (string) – Store computed values during construction on the specified file path. The stored values are ttcross_Jinit and the values used in the TensorWrapper. This permits a restart from already computed values. If empty string nothing is done. (method==’ttcross’)
  • store_object (string) – Object to be stored (default are the tensor wrapper and ttcross_Jinit)
  • store_freq (int) – storage frequency. store_freq==1 stores intermediate values at every iteration. The program stores data every store_freq internal iterations. If store_object is a SpectralTensorTrain, then store_freq determines the number of seconds every which to store values.
  • multidim_point (int) – If the object A returns a multidimensional array, then this can be used to define which point to apply ttcross to.
project(Vs=None, Ws=None, eps=1e-08, is_sparse=None)

Project the TTvec onto a set of basis provided, using the Generalized Vandermonde matrices ``Vs’’ and weights ``Ws’‘.

Parameters:
  • Vs (list) – list of generalized Vandermonde matrices for each dimension. Ms[i].shape[1] == self.shape()[i]
  • Ws (list) – list of weights for each dimension. Ws[i].shape[0] == self.shape()[i]
  • eps (float) – tolerance with which to perform the rounding after interpolation
  • is_sparse (list) – is_sparse[i] is a bool indicating whether Ms[i] is sparse or not. If ‘None’ all matrices are non sparse
Returns:

TTvec containting the Fourier coefficients

Return type:

TTvec

>>> from DABISpectralToolbox import DABISpectral1D as S1D
>>> P = S1D.Poly1D(S1D.JACOBI,(0,0))
>>> x,w = S1D.Quadrature(10,S1D.GAUSS)
>>> X = [x]*d
>>> W = [w]*d
>>> # Compute here the TTapprox at points X
>>> TTapprox = TTvec(....)
>>> # Project
>>> Vs = [ P.GradVandermonde1D(x,10,0,norm=False) ] * d
>>> is_sparse = [False]*d
>>> TTfourier = TTapprox.project(Vs,W,eps=1e-8,is_sparse=is_sparse)
shape()

Returns the shape of the tensor represented

ttcross(A, lr_r, lr_Jinit, lr_delta, lr_maxit, mv_eps, mv_maxit, store_init=True, lr_store_location='', store_object=None, store_freq=1, multidim_point=None)

Construct a TT representation of A using TT cross

Parameters:
  • A (nd.array/TensorWrapper) –
  • lr_r (list) – list of upper ranks (A.ndim)
  • lr_Jinit (list) – list (A.ndim-1) of lists of init indices
  • lr_store_location (string) – Store computed values during construction on the specified file path. The stored values are ttcross_Jinit and the values used in the TensorWrapper. This permits a restart from already computed values. If empty string nothing is done. (method==’ttcross’)
  • store_object (string) – Object to be stored (default are the tensor wrapper and ttcross_Jinit)
  • store_freq (int) – storage frequency. store_freq==1 stores intermediate values at every iteration. The program stores data every store_freq internal iterations. If store_object is a SpectralTensorTrain, then store_freq determines the number of seconds every which to store values.
  • multidim_point (int) – If the object A returns a multidimensional array, then this can be used to define which point to apply ttcross to.
TensorToolbox.core.randvec(d, N)

Returns the rank-1 multidimensional random vector in Tensor Train format

Args:
d (int): number of dimensions N (int or list): If int then uniform sizes are used for all the dimensions, if list of int then len(N) == d and each dimension will use different size
Returns:
TTvec The rank-1 multidim random vector in Tensor Train format
TensorToolbox.core.zerosvec(d, N)

Returns the rank-1 multidimensional vector of zeros in Tensor Train format

Args:
d (int): number of dimensions N (int or list): If int then uniform sizes are used for all the dimensions, if list of int then len(N) == d and each dimension will use different size
Returns:
TTvec The rank-1 multidim vector of zeros in Tensor Train format
class TensorToolbox.core.TTmat(A, nrows, ncols, eps=1e-08, is_sparse=None, sparse_ranks=None)

Constructor of multidimensional matrix in Tensor Train format

Parameters:
  • A (Candecomp,ndarray,TT) – Available input formats are Candecomp, full tensor in numpy.ndarray, Tensor Train structure (list of cores), list of sparse matrices of sizes (r_{i-1}*r_{i}*nrows x ncols) (used for fast dot product - limited support for other functionalities)
  • nrows (list,int) – If int then the row size will be the same in all dimensions, if list then len(nrows) == len(self.TT) (numer of cores) and row size will change for each dimension.
  • ncols (list,int) – If int then the column size will be the same in all dimensions, if list then len(ncols) == len(self.TT) (numer of cores) and column size will change for each dimension.
  • eps (float) – [default == 1e-8] precision with which to approximate the input tensor
  • is_sparse (bool) – [default == False] if True it uses sparsity to accelerate some computations
  • sparse_ranks (list) – [default==None] mandatory argument when A is a list of sparse matrices. It contains integers listing the TT-ranks of the matrix.

Note

the method __getitem__ is not overwritten, thus the indices used to access the tensor refer to the flatten versions of the matrices composing the matrix tensor.

TensorToolbox.core.eye(d, N)

Returns the multidimensional identity operator in Tensor Train format

Args:
d (int): number of dimensions N (int or list): If int then uniform sizes are used for all the dimensions, if list of int then len(N) == d and each dimension will use different size
Returns:
TTmat The multidim identity matrix in Tensor Train format
Note:
TODO: improve construction avoiding passage through Candecomp
TensorToolbox.core.randmat(d, nrows, ncols)

Returns the rank-1 multidimensional random matrix in Tensor Train format

Args:
d (int): number of dimensions nrows (int or list): If int then uniform sizes are used for all the dimensions, if list of int then len(nrows) == d and each dimension will use different size ncols (int or list): If int then uniform sizes are used for all the dimensions, if list of int then len(ncols) == d and each dimension will use different size
Returns:
TTmat The rank-1 multidim random matrix in Tensor Train format
class TensorToolbox.core.QTTvec(A, base, shape=None, eps=1e-10)

Constructor of multidimensional tensor in Quantics Tensor Train format

Parameters:
  • A (ndarray,TT) – Available input formats are full tensor in numpy.ndarray, Tensor Train structure (list of cores)
  • base (int) – folding base for QTT representation
  • shape (list,int) – if QTTvec is constructed from a list of cores, shape must be provided to describe the original shape of the vector
  • eps (float) – [default == 1e-8] precision with which to approximate the input tensor
fullshape()

Return the shape of the folded tensor

TensorToolbox.core.QTTzerosvec(d, N, base)

Returns the rank-1 multidimensional vector of zeros in Quantics Tensor Train format

Args:
d (int): number of dimensions N (int or list): If int then uniform sizes are used for all the dimensions, if list of int then len(N) == d and each dimension will use different size base (int): QTT base
Returns:
QTTvec The rank-1 multidim vector of zeros in Tensor Train format
class TensorToolbox.core.QTTmat(A, base, nrows, ncols, eps=1e-08, is_sparse=False)

Constructor of multidimensional matrix in Quantics Tensor Train format

Parameters:
  • A (ndarray,TT) – Available input formats are full tensor in numpy.ndarray, Tensor Train structure (list of cores). If input is ndarray, then it must be in mattensor format (see aux.py)
  • base (int) – folding base for QTT representation
  • nrows (int) – If int then the row size will be the same in all dimensions, if list then len(nrows) == len(self.TT) (numer of cores) and row size will change for each dimension.
  • ncols (int) – If int then the column size will be the same in all dimensions, if list then len(ncols) == len(self.TT) (numer of cores) and column size will change for each dimension.
  • eps (float) – [default == 1e-8] precision with which to approximate the input tensor
get_fullncols()

Returns the number of cols of the unfolded matrices

get_fullnrows()

Returns the number of rows of the unfolded matrices

get_ncols()

Returns the number of cols of the folded matrices

get_nrows()

Returns the number of rows of the folded matrices

ndims()

Return the number of dimensions of the tensor space

class TensorToolbox.core.STT(f, grids, params, range_dim=0, marshall_f=True, surrogateONOFF=False, surrogate_type=None, orders=None, orderAdapt=None, eps=0.0001, lr_r=None, lr_fix_rank=False, lr_Jinit=None, lr_delta=0.0001, lr_maxit=100, mv_eps=1e-06, mv_maxit=100, stt_store_location='', stt_store_overwrite=False, stt_store_freq=0, maxprocs=None, empty=False)

Constructor of the Spectral Tensor Train approximation. Given a function f(x,theta,params):(Is, It) -> R with dim(Is)=n and dim(It)=d, construct an approximation of g(theta,params): It -> h_t(Is). For example Is could be the discretization of a spatial dimension, and It some parameter space, so that f(x,theta,params) describes a scalar field depending some parameters that vary in It. The params in the definition of f can be constants used by the function or othere objects that must be passed to the function definition.

Parameters:
  • f (function) – multidimensional function to be approximated with format f(x,theta,params)
  • grids (list) – this is a list with len(grids)=dim(Is)+dim(It) which can contain: a) 1-dimensional numpy.array of points discretizing the i-th dimension, b) a tuple (PolyType,QuadType,PolyParams,span) where PolyType is one of the polynomials available in SpectralToolbox.Spectral1D and QuadType is one of the quadrature rules associated to the selected polynomial and PolyParams are the parameters for the selected polynomial. span is a tuple defining the left and right end for dimension i (Example: (-3,np.inf)) c) a tuple (QuadType,span) where QuadType is one of the quadrature rules available in SpectralToolbox.Spectral1D without the selection of a particular polynomial type, and span is defined as above.
  • params (object) – any list of parameters to be passed to the function f
  • range_dim (int) – define the dimension of the spatial dimension Is. For functionals f(theta,params), dim(Is)=0. For scalar fileds in 3D, dim(Is)=3.
  • marshall_f (bool) – whether to marshall the function f or not. For MPI support, the function f must be marshallable (does this adverb exists??).
  • surrogateONOFF (bool) – whether to construct the surrogate or not
  • surrogate_type (str) – whether the surrogate will be an interpolating surrogate (TensorTrain.LINEAR_INTERPOLATION or TensorTrain.LAGRANGE_INTERPOLATION) or a projection surrogate (TensorTrain.PROJECTION)
  • orders (list) – polynomial orders for each dimension if TensorTrain.PROJECTION is used. If orderAdapt==True then the orders are starting orders that can be increased as needed by the construction algorithm. If this parameter is not provided but orderAdapt==True, then the starting order is 1 for all the dimensions.
  • orderAdapt (bool) – whether the order is fixed or not.
  • stt_store_location (str) – path to a file where function evaluations can be stored and used in order to restart the construction.
  • stt_store_overwrite (bool) – whether to overwrite pre-existing files
  • stt_store_freq (int) – storage frequency. Determines every how many seconds the state is stored. stt_store_freq==0 stores every time it is possible.
  • empty (bool) – Creates an instance without initializing it. All the content can be initialized using the setstate() function.

Note

For a description of the remaining parameters see TTvec.

__getitem__()
__call__(x, verbose=False)

Evaluate the surrogate on points x

Parameters:x (np.ndarray) – 1 or 2 dimensional array of points in the parameter space where to evaluate the function. In 2 dimensions, each row is an entry, i.e. x.shape[1] == self.param_dim
Returns:an array with dimension equal to the space dimension (range_dim) plus one. If A is the returned vector and range_dim=2, then A[:,:,i] is the value of the surrogate for x[i,:]
integrate()

Compute the integral of the approximated function

Returns:an array with dimension equal to the space dimension (range_dim), containing the value of the integral.
class TensorToolbox.core.Candecomp(A)
class TensorToolbox.core.TTvec(A, eps=1e-10, method='svd', lr_r=None, lr_fix_rank=False, lr_Jinit=None, lr_delta=0.0001, lr_maxit=100, mv_eps=1e-06, mv_maxit=100, lr_store_location='', store_object=None, store_freq=1, generate=True)

Constructor of multidimensional tensor in Tensor Train format

Parameters:
  • A (Candecomp,ndarray,TT) – Available input formats are Candecomp, full tensor in numpy.ndarray, Tensor Train structure (list of cores)
  • generate (bool) – whether to perform the construction or just initialize the object
  • method (string) – ‘svd’ use singular value decomposition to construct the TT representation, ‘ttcross’ use low rank skeleton approximation to construct the TT representation.
  • eps (float) – [default == 1e-10] For method==’svd’: precision with which to approximate the input tensor. For method==’ttcross’: TT-rounding tolerance for rank-check.
  • lr_r (list) – list of integer ranks of different cores. If None then the incremental TTcross approach will be used. (method==’ttcross’)
  • lr_fix_rank (bool) – determines whether the rank is allowed to be increased (method==’ttcross’)
  • lr_Jinit (list) – list of list of integers containing the r starting columns in the lowrankapprox routine for each core. If None then pick them randomly. (method==’ttcross’)
  • lr_delta (float) – accuracy parameter in the TT-cross routine (method==’ttcross’). It is the relative error in Frobenious norm between two successive iterations.
  • lr_maxit (int) – maximum number of iterations in the lowrankapprox routine (method==’ttcross’)
  • mv_eps (float) – accuracy parameter for each usage of the maxvol algorithm (method==’ttcross’)
  • mv_maxit (int) – maximum number of iterations in the maxvol routine (method==’ttcross’)
  • fix_rank (bool) – Whether the rank is allowed to increase
  • lr_store_location (string) – Store computed values during construction on the specified file path. The stored values are ttcross_Jinit and the values used in the TensorWrapper. This permits a restart from already computed values. If empty string nothing is done. (method==’ttcross’)
  • store_object (string) – Object to be stored (default are the tensor wrapper and ttcross_Jinit)
  • store_freq (int) – storage frequency. store_freq==1 stores intermediate values at every iteration. The program stores data every store_freq internal iterations. If store_object is a SpectralTensorTrain, then store_freq determines the number of seconds every which to store values.
__getitem__(idxs)
interpolate(Ms=None, eps=1e-08, is_sparse=None)

Interpolates the values of the TTvec at arbitrary points, using the interpolation matrices ``Ms’‘.

Parameters:
  • Ms (list) – list of interpolation matrices for each dimension. Ms[i].shape[1] == self.shape()[i]
  • eps (float) – tolerance with which to perform the rounding after interpolation
  • is_sparse (list) – is_sparse[i] is a bool indicating whether Ms[i] is sparse or not. If ‘None’ all matrices are non sparse
Returns:

TTvec interpolation

Return type:

TTvec

>>> from DABISpectralToolbox import DABISpectral1D as S1D
>>> Ms = [ S1D.LinearInterpolationMatrix(X[i],XI[i]) for i in range(d) ]
>>> is_sparse = [True]*d
>>> TTapproxI = TTapprox.interpolate(Ms,eps=1e-8,is_sparse=is_sparse)
outer_ttcross(eps, lr_r, lr_Jinit, lr_delta, lr_maxit, mv_eps, mv_maxit, fix_rank=False, lr_store_location='', store_object=None, store_freq=1, multidim_point=None)

Construct a TT representation of A using TT cross. This routine manage the outer loops for incremental ttcross or passes everything to ttcross if lr_r are specified.

Parameters:
  • eps (float) – tolerance with which to perform the TT-rounding and check the rank accuracy
  • lr_r (list) – list of upper ranks (A.ndim)
  • lr_Jinit (list) – list (A.ndim-1) of lists of init indices
  • lr_delta (float) – TT-cross accuracy
  • lr_maxit (int) – maximum number of iterations for ttcross
  • mv_eps (float) – MaxVol accuracy
  • mv_maxit (int) – maximum number of iterations for MaxVol
  • fix_rank (bool) – Whether the rank is allowed to increase
  • lr_store_location (string) – Store computed values during construction on the specified file path. The stored values are ttcross_Jinit and the values used in the TensorWrapper. This permits a restart from already computed values. If empty string nothing is done. (method==’ttcross’)
  • store_object (string) – Object to be stored (default are the tensor wrapper and ttcross_Jinit)
  • store_freq (int) – storage frequency. store_freq==1 stores intermediate values at every iteration. The program stores data every store_freq internal iterations. If store_object is a SpectralTensorTrain, then store_freq determines the number of seconds every which to store values.
  • multidim_point (int) – If the object A returns a multidimensional array, then this can be used to define which point to apply ttcross to.
project(Vs=None, Ws=None, eps=1e-08, is_sparse=None)

Project the TTvec onto a set of basis provided, using the Generalized Vandermonde matrices ``Vs’’ and weights ``Ws’‘.

Parameters:
  • Vs (list) – list of generalized Vandermonde matrices for each dimension. Ms[i].shape[1] == self.shape()[i]
  • Ws (list) – list of weights for each dimension. Ws[i].shape[0] == self.shape()[i]
  • eps (float) – tolerance with which to perform the rounding after interpolation
  • is_sparse (list) – is_sparse[i] is a bool indicating whether Ms[i] is sparse or not. If ‘None’ all matrices are non sparse
Returns:

TTvec containting the Fourier coefficients

Return type:

TTvec

>>> from DABISpectralToolbox import DABISpectral1D as S1D
>>> P = S1D.Poly1D(S1D.JACOBI,(0,0))
>>> x,w = S1D.Quadrature(10,S1D.GAUSS)
>>> X = [x]*d
>>> W = [w]*d
>>> # Compute here the TTapprox at points X
>>> TTapprox = TTvec(....)
>>> # Project
>>> Vs = [ P.GradVandermonde1D(x,10,0,norm=False) ] * d
>>> is_sparse = [False]*d
>>> TTfourier = TTapprox.project(Vs,W,eps=1e-8,is_sparse=is_sparse)
shape()

Returns the shape of the tensor represented

ttcross(A, lr_r, lr_Jinit, lr_delta, lr_maxit, mv_eps, mv_maxit, store_init=True, lr_store_location='', store_object=None, store_freq=1, multidim_point=None)

Construct a TT representation of A using TT cross

Parameters:
  • A (nd.array/TensorWrapper) –
  • lr_r (list) – list of upper ranks (A.ndim)
  • lr_Jinit (list) – list (A.ndim-1) of lists of init indices
  • lr_store_location (string) – Store computed values during construction on the specified file path. The stored values are ttcross_Jinit and the values used in the TensorWrapper. This permits a restart from already computed values. If empty string nothing is done. (method==’ttcross’)
  • store_object (string) – Object to be stored (default are the tensor wrapper and ttcross_Jinit)
  • store_freq (int) – storage frequency. store_freq==1 stores intermediate values at every iteration. The program stores data every store_freq internal iterations. If store_object is a SpectralTensorTrain, then store_freq determines the number of seconds every which to store values.
  • multidim_point (int) – If the object A returns a multidimensional array, then this can be used to define which point to apply ttcross to.
class TensorToolbox.core.TTmat(A, nrows, ncols, eps=1e-08, is_sparse=None, sparse_ranks=None)

Constructor of multidimensional matrix in Tensor Train format

Parameters:
  • A (Candecomp,ndarray,TT) – Available input formats are Candecomp, full tensor in numpy.ndarray, Tensor Train structure (list of cores), list of sparse matrices of sizes (r_{i-1}*r_{i}*nrows x ncols) (used for fast dot product - limited support for other functionalities)
  • nrows (list,int) – If int then the row size will be the same in all dimensions, if list then len(nrows) == len(self.TT) (numer of cores) and row size will change for each dimension.
  • ncols (list,int) – If int then the column size will be the same in all dimensions, if list then len(ncols) == len(self.TT) (numer of cores) and column size will change for each dimension.
  • eps (float) – [default == 1e-8] precision with which to approximate the input tensor
  • is_sparse (bool) – [default == False] if True it uses sparsity to accelerate some computations
  • sparse_ranks (list) – [default==None] mandatory argument when A is a list of sparse matrices. It contains integers listing the TT-ranks of the matrix.

Note

the method __getitem__ is not overwritten, thus the indices used to access the tensor refer to the flatten versions of the matrices composing the matrix tensor.

class TensorToolbox.core.STT(f, grids, params, range_dim=0, marshall_f=True, surrogateONOFF=False, surrogate_type=None, orders=None, orderAdapt=None, eps=0.0001, lr_r=None, lr_fix_rank=False, lr_Jinit=None, lr_delta=0.0001, lr_maxit=100, mv_eps=1e-06, mv_maxit=100, stt_store_location='', stt_store_overwrite=False, stt_store_freq=0, maxprocs=None, empty=False)

Constructor of the Spectral Tensor Train approximation. Given a function f(x,theta,params):(Is, It) -> R with dim(Is)=n and dim(It)=d, construct an approximation of g(theta,params): It -> h_t(Is). For example Is could be the discretization of a spatial dimension, and It some parameter space, so that f(x,theta,params) describes a scalar field depending some parameters that vary in It. The params in the definition of f can be constants used by the function or othere objects that must be passed to the function definition.

Parameters:
  • f (function) – multidimensional function to be approximated with format f(x,theta,params)
  • grids (list) – this is a list with len(grids)=dim(Is)+dim(It) which can contain: a) 1-dimensional numpy.array of points discretizing the i-th dimension, b) a tuple (PolyType,QuadType,PolyParams,span) where PolyType is one of the polynomials available in SpectralToolbox.Spectral1D and QuadType is one of the quadrature rules associated to the selected polynomial and PolyParams are the parameters for the selected polynomial. span is a tuple defining the left and right end for dimension i (Example: (-3,np.inf)) c) a tuple (QuadType,span) where QuadType is one of the quadrature rules available in SpectralToolbox.Spectral1D without the selection of a particular polynomial type, and span is defined as above.
  • params (object) – any list of parameters to be passed to the function f
  • range_dim (int) – define the dimension of the spatial dimension Is. For functionals f(theta,params), dim(Is)=0. For scalar fileds in 3D, dim(Is)=3.
  • marshall_f (bool) – whether to marshall the function f or not. For MPI support, the function f must be marshallable (does this adverb exists??).
  • surrogateONOFF (bool) – whether to construct the surrogate or not
  • surrogate_type (str) – whether the surrogate will be an interpolating surrogate (TensorTrain.LINEAR_INTERPOLATION or TensorTrain.LAGRANGE_INTERPOLATION) or a projection surrogate (TensorTrain.PROJECTION)
  • orders (list) – polynomial orders for each dimension if TensorTrain.PROJECTION is used. If orderAdapt==True then the orders are starting orders that can be increased as needed by the construction algorithm. If this parameter is not provided but orderAdapt==True, then the starting order is 1 for all the dimensions.
  • orderAdapt (bool) – whether the order is fixed or not.
  • stt_store_location (str) – path to a file where function evaluations can be stored and used in order to restart the construction.
  • stt_store_overwrite (bool) – whether to overwrite pre-existing files
  • stt_store_freq (int) – storage frequency. Determines every how many seconds the state is stored. stt_store_freq==0 stores every time it is possible.
  • empty (bool) – Creates an instance without initializing it. All the content can be initialized using the setstate() function.

Note

For a description of the remaining parameters see TTvec.

__getitem__()
__call__(x, verbose=False)

Evaluate the surrogate on points x

Parameters:x (np.ndarray) – 1 or 2 dimensional array of points in the parameter space where to evaluate the function. In 2 dimensions, each row is an entry, i.e. x.shape[1] == self.param_dim
Returns:an array with dimension equal to the space dimension (range_dim) plus one. If A is the returned vector and range_dim=2, then A[:,:,i] is the value of the surrogate for x[i,:]
integrate()

Compute the integral of the approximated function

Returns:an array with dimension equal to the space dimension (range_dim), containing the value of the integral.
TensorToolbox.multilinalg.mul(A, B)
  • If A,B are TTvec/TTmat -> Hadamard product of two TT tensors
  • If A TTvec/TTmat and B scalar -> multiplication by scalar
TensorToolbox.multilinalg.kron(A, B)

Kron product between two tensors in TT format. Complexity: O(1)

TensorToolbox.multilinalg.contraction(A, U)

Multidimensional contraction of tensor A with vectors in list U. Complexity: O(dnr^2)

Syntax:
W = contraction(A,U)
Parameters:
  • A – Tensor in some form
  • U – list of vectors of dimensions n_k for performing the contraction
TensorToolbox.multilinalg.norm(A, ord='fro', round_eps=1e-10, eps=0.0001, maxit=1000, pow_guess=None, info=False)

Compute the norm of tensor A

Syntax:
w = norm(A,[ord])
Parameters:
  • A – Tensor in some form
  • ord – Specifies the type of norm that needs to be computed. Available norms are * Frobenius norm: ‘fro’
TensorToolbox.multilinalg.sd(A, b, x0=None, eps=1e-08, maxit=1000, eps_round=1e-10, ext_info=False)

Solves the system \(Ax=b\) using the Steepest Descent method in Tensor Train format.

Parameters:
  • A (TTmat) – Tensor train matrix
  • b (TTvec/ndarray) – Right hand side
  • x0 (TTvec/ndarray) – [default == TensorToolbox.core.zerosvec()] initial guess of solution x
  • eps (float) – [default == 1e-8] stop criteria
  • maxit (int) – [default == 1000] maximum number of iterations
  • eps_round (float) – [default == 1e-10] accuracy for Tensor Train rounding operations
  • ext_info (bool) – [default == False] whehter of not to have additional info returned
Returns:

tuple (x,conv,info)

  • x (TTvec): solution of the linear system if converged or last iterate if not converged
  • conv (bool): True -> converged, False -> Not converged / Zero Inner Product exeception
  • info (dict): iter -> total number of iterations; r -> last residual in TT format; res -> residual history

TensorToolbox.multilinalg.cg(A, b, x0=None, eps=1e-08, maxit=1000, eps_round=1e-10, ext_info=False)

Solves the system \(Ax=b\) using the Conjugate Gradient method in Tensor Train format.

Parameters:
  • A (TTmat) – Tensor train matrix
  • b (TTvec/ndarray) – Right hand side
  • x0 (TTvec/ndarray) – [default == TensorToolbox.core.zerosvec()] initial guess of solution x
  • eps (float) – [default == 1e-8] stop criteria for Bi-CGSTAB iterations
  • maxit (int) – [default == 1000] maximum number of iterations for Bi-CGSTAB
  • eps_round (float) – [default == 1e-10] accuracy for Tensor Train rounding operations
  • ext_info (bool) – [default == False] whehter of not to have additional info returned
Returns:

tuple (x,conv,info)

  • x (TTvec): solution of the linear system if converged or last iterate if not converged
  • conv (bool): True -> converged, False -> Not converged / Zero Inner Product exeception
  • info (dict): iter -> total number of iterations; r -> last residual in TT format; res -> residual history

TensorToolbox.multilinalg.bicgstab(A, b, x0=None, eps=1e-08, maxit=1000, eps_round=1e-10, ext_info=False)

Solves the system \(Ax=b\) using the Bi-Conjugate Gradient Stabilized method using Tensor Train format.

Parameters:
  • A (TTmat) – Tensor train matrix
  • b (TTvec) – Right hand side
  • x0 (TTvec) – [default == TensorToolbox.core.zerosvec()] initial guess of solution x
  • eps (float) – [default == 1e-8] stop criteria for Bi-CGSTAB iterations
  • maxit (int) – [default == 1000] maximum number of iterations for Bi-CGSTAB
  • eps_round (float) – [default == 1e-10] accuracy for Tensor Train rounding operations
  • ext_info (bool) – [default == False] whehter of not to have additional info returned
Returns:

tuple (x,conv,info)

  • x (TTvec): solution of the linear system if converged or last iterate if not converged
  • conv (bool): True -> converged, False -> Not converged / Zero Inner Product exeception
  • info (dict): iter -> total number of iterations; r -> last residual in TT format; rho -> last value of dot(r0,r) must be bigger than np.spacing(1); r0v -> last value of dot(r0,v) must be bigger than np.spacing(1)

TensorToolbox.multilinalg.gmres(A, b, x0=None, eps=1e-08, maxit=1000, restart=1000, eps_round=1e-10, ext_info=False)

Solves the system \(Ax=b\) using the Generalized Minimum Residual method with Modified Gram-Schmidt iterations using Tensor Train format.

Parameters:
  • A (TTmat) – Tensor train matrix
  • b (TTvec) – Right hand side
  • x0 (TTvec) – [default == TensorToolbox.core.zerosvec()] initial guess of solution x
  • eps (float) – [default == 1e-8] stop criteria for GMRES iterations
  • maxit (int) – [default == 1000] maximum number of iterations for GMRES
  • restart (int) – [default == 1000] restart constant for GMRES (nothing is implemented to retain information, i.e. Hessemberg and Krylov space are reset)
  • eps_round (float) – [default == 1e-10] accuracy for Tensor Train rounding operations
  • ext_info (bool) – [default == False] whehter of not to have additional info returned
Returns:

tuple (x,conv,info)

  • x (TTvec): solution of the linear system if converged or last iterate if not converged
  • conv (bool): True -> converged, False -> Not converged / Zero Inner Product exeception
  • info (dict): iter -> total number of iterations; TT_r -> last residual in TT format; res -> norm of last residual; err -> residual history per iteration

Note:

not optimized for symmetric A

Indices and tables

Table Of Contents

This Page