API

API #

Here you may find description of functions and methods avaliable in tucker_riemopt.

Tucker #

Base interface #

class tucker_riemopt.tucker.tucker.Tucker(core: ~torch.Tensor = <factory>, factors: ~typing.List[~torch.Tensor] = <factory>)#

Tucker tensor factorisation.

Parameters:

core – The core tensor of the decomposition.
factors – The list of factors of the decomposition.

property dtype: type#

Get dtype of the elements of the tensor.

Returns:: dtype.

flat_inner(other: Tucker) → float#

Calculate inner product of given Tucker tensors.

Parameters:: other – Tucker tensor.
Returns:: Result of inner product.

classmethod from_dense(dense_tensor: Tensor, eps=1e-14)#

Convert dense tensor into Tucker representation.

Parameters:

dense_tensor – Dense tensor that will be factorized.
eps – Precision of approximation.

Returns:

Tucker representation of the provided dense tensor.

k_mode_product(k: int, matrix: Tensor)#

k-mode tensor-matrix contraction.

Parameters:

k – Integer from 0 to d-1.
matrix – Must contain self.rank[k] columns.

Returns:

Tucker tensor.

property ndim: int#

Number of dimensions of the tensor.

Returns:: Dimensionality of the tensor.

norm(qr_based: bool = False) → float#

Frobenius norm of Tucker tensor.

Parameters:: qr_based – Whether to use stable QR-based implementation of norm, which is not differentiable, or unstable but differentiable implementation based on inner product. By default, differentiable implementation used.
Returns:: Non-negative number which is the Frobenius norm of Tucker tensor.

property rank: Sequence[int]#

Get multilinear rank of Tucker tensor.

Returns:: Sequence that represents the multilinear rank of tensor.

round(max_rank: int | Sequence[int] | None = None, eps=1e-14)#

Perform rounding procedure. The Tucker tensor will be approximated by Tucker tensor with rank at most max_rank.

Parameters:

max_rank – Maximum possible multilinear rank of the approximation. Expects a sequence of integers, but if a single number is provided, it will be treated as a sequence with all components equal. If None provided, will be performed approximation with precision eps.
eps – Precision of the approximation.

Returns:

Tucker tensor.

property shape: Sequence[int]#

Shape of Tucker tensor.

Returns:: Sequence that represents the shape of Tucker tensor.

classmethod sparse2tuck(sparse_tensor: SparseTensor, max_rank: int | Sequence[int] | None = None, maxiter: int | None = 5)#

Accept sparse tensor and construct its Sparse Tucker decomposition.

Parameters:

sparse_tensor – Tensor in sparse format.
max_rank – If number, then defines the maximal rank of the result; If a list of numbers, then max_rank length should be d (number of dimensions) and max_rank[i] defines the (i)-th rank of the result. The following two versions are equivalent: max_rank = r and max_rank = [r] * d.
maxiter – If int, the HOOI algorithm will be executed until the specified number of iterations is reached. If None, no additional algorithms will be launched (note, that approximation error in that case may be large).

to_dense() → Tensor#

Convert Tucker tensor to dense representation.

Returns:: Dense d-dimensional representation of Tucker tensor.

class tucker_riemopt.tucker.matrix.TuckerMatrix(core: ~torch.Tensor = <factory>, factors: ~typing.List[~torch.Tensor] = <factory>, n: ~typing.Sequence[int] | None = None, m: ~typing.Sequence[int] | None = None)#

Tucker representation for operators.

Parameters:

core – The core tensor of the decomposition.
factors – The list of factors of the decomposition.
n – Dimensionality of source space (see from_dense method).
m – Dimensionality of target space (see from_dense method).

classmethod from_dense(dense_tensor: Tensor, n: Sequence[int] | None = None, m: Sequence[int] | None = None, eps=1e-14)#

Convert dense tensor into TuckerMatrix representation. The resul is tensor that represents linear operator from R^N to R^M.

Parameters:

dense_tensor – Dense tensor that will be factorized.
n – Sequence of ints (n_1, …, n_a) such that N = n_1 * … * n_a.
m – Sequence of ints (m_1, …, m_b) such that M = m_1 * … * m_b.
eps – Precision of approximation.

Returns:

TuckerMatrix representation of the provided dense tensor.

Riemannian #

class tucker_riemopt.tucker.riemannian.TangentVector(manifold_point, delta_core: None | Tensor = None, delta_factors: None | Tensor = None)#

Special representation for tangent vectors of some point from the manifold.

Parameters:

point – Point from the manifold of tensors of fixed multilinear (Tucker) rank.
delta_core – Tangent vector delta core.
delta_factors – Tangent vector delta factors.

construct()#

Build Tucker tensor from TangentVector representation with at most twice bigger rank.

Returns:: Tucker tensor.

static group_cores(corner_core, padding_core)#

Combine point’s core and delta core into unite core of tangent vector.

Parameters:

corner_core – Corner block of the grouped core.
padding_core – Adjacent block of the grouped core.

Returns:

Grouped core.

norm()#

Norm of tangent vector. This method is not differentiable as applies series of QR decompositions.

Returns:: Frobenius norm of tangent vector.

tucker_riemopt.tucker.riemannian.grad(f: Callable[[Tucker], float], X: Tucker, retain_graph=False) → Tuple[TangentVector, float]#

Compute the Riemannian gradient of the smooth scalar valued function f at point X. The result is the tangent: vector of X. Also returns value f(X).

Parameters:

f – Smooth scalar valued function.
X – Point from the manifold.
retain_graph – Optional argument, which may be provided to autodiff framework (e.g. pytorch).

Returns:

A tangent vector of X which is the Riemannian gradient of f and value f(X).

tucker_riemopt.tucker.riemannian.project(X: Tucker, xi: Tucker, retain_graph=False) → TangentVector#

Project xi onto the tangent space of X.

Parameters:

X – Point from the manifold.
xi – Arbitrary tensor represented in Tucker format.

Returns:

Result of projection of xi onto the tangent space of X.

SF-Tucker #

Base interface #

class tucker_riemopt.sf_tucker.sf_tucker.SFTucker(core: ~torch.Tensor = <factory>, factors: ~typing.List[~torch.Tensor] = <factory>, num_shared_factors: int = 0, shared_factor: None | ~torch.Tensor = None)#

SFTucker tensor factorisation. All shared modes are gathered at the end.

Parameters:

core – The core tensor of the decomposition.
factors – The list of regular factors of the decomposition.
num_shared_factors – Number of shared factors.
shared_factor – Shared factor.

property ds: int#

Amount of shared modes.

Returns:: Amount of modes with shared factors.

property dt: int#

Amount of regular modes.

Returns:: Amount of modes with regular factors.

property dtype: type#

Get dtype of the elements of the tensor.

Returns:: dtype.

flat_inner(other: SFTucker)#

Calculate inner product of given SFTucker tensors.

Parameters:: other – SFTucker tensor.
Returns:: Result of inner product.

classmethod from_dense(dense_tensor: Tensor, ds: int | None = None, eps=1e-14)#

Convert dense tensor into SFTucker representation.

Parameters:

dense_tensor – Dense tensor that will be factorized.
ds – Number of shared factors.
sft_rank – Desired SFT rank. If None, then parameter eps must be provided.
eps – If sft_rank is None, then eps represents precision of approximation. If sft_rank is not None, then ignored.

Returns:

SFTucker representation of the provided dense tensor.

classmethod from_tucker(tucker_tensor: Tucker, ds: int | None = None, eps=1e-14)#

Converts Tucker tensor into SFTucker representation.

Parameters:

tucker_tensor – Tucker tensor that will be transformed into SFTucker.
ds – Number of shared factors.
sft_rank – Desired SFT rank. If None, then parameter eps must be provided.
eps – If sft_rank is None, then eps represents precision of approximation. If sft_rank is not None, then ignored.

Returns:

SFTucker representation of the provided dense tensor.

k_mode_product(k: int, matrix: Tensor)#

k-mode tensor-matrix contraction.

Parameters:

k – Integer from 0 to d-1.
matrix – Must contain self.rank[k] columns.

Returns:

SFTucker tensor.

property ndim: int#

Number of dimensions of the tensor.

Returns:: Dimensionality of the tensor.

norm(qr_based: bool = False)#

Frobenius norm of SFTucker tensor.

Parameters:: qr_based – Whether to use stable QR-based implementation of norm, which is not differentiable, or unstable but differentiable implementation based on inner product. By default, differentiable implementation is used.
Returns:: Non-negative number which is the Frobenius norm of SFTucker tensor.

property rank: List[int]#

Get SFT rank of SFTucker tensor.

Returns:: Sequence that represents the SFT rank of tensor.

property regular_factors#

Alias for factors.

Returns:: Factors.

round(max_rank: Sequence[int] | None = None, eps=1e-14)#

Perform rounding procedure. The SFTucker tensor will be approximated by SFTucker tensor with rank at most max_rank.

Parameters:

max_rank – Maximum possible SFT rank of the approximation. Expects a sequence of integers. If provided a sequence of two elements, then the first element is treated as a value of a multilinear part of rank with all equal components. If None provided, will be performed approximation with precision eps. For example, if max_rank=[2, 5] for three-dimensional tensor, then actual SFT rank is treated as [2, 2, 5].
eps – Precision of approximation.

Returns:

Tucker tensor.

property shape: Sequence[int]#

Shape of SFTucker tensor.

Returns:: Sequence that represents the shape of SFTucker tensor.

shared_modes_product(matrix: Tensor)#

Tensor-matrix contraction by shared modes.

Parameters:: matrix – Must contain self.rank[-1] columns.
Returns:: SFTucker tensor.

to_dense()#

Convert SFTucker tensor to dense representation.

Returns:: Dense d-dimensional representation of SFTucker tensor.

SF-Tucker matrix #

class tucker_riemopt.sf_tucker.matrix.SFTuckerMatrix(core: ~torch.Tensor = <factory>, factors: ~typing.List[~torch.Tensor] = <factory>, num_shared_factors: int = 0, shared_factor: None | ~torch.Tensor = None, n: ~typing.Sequence[int] | None = None, m: ~typing.Sequence[int] | None = None)#

Tucker representation for operators.

Parameters:

core – The core tensor of the decomposition.
factors – The list of factors of the decomposition.
num_shared_factors – Number of shared factors.
shared_factor – Shared factor.
n – Dimensionality of source space (see from_dense method).
m – Dimensionality of target space (see from_dense method).

classmethod from_dense(dense_tensor: Tensor, ds: int | None = None, n: Sequence[int] | None = None, m: Sequence[int] | None = None, eps=1e-14)#

Convert dense tensor into TuckerMatrix representation. The resul is tensor that represents linear operator from R^N to R^M.

Parameters:

dense_tensor – Dense tensor that will be factorized.
ds – Number of shared factors.
n – Sequence of ints (n_1, …, n_a) such that N = n_1 * … * n_a.
m – Sequence of ints (m_1, …, m_b) such that M = m_1 * … * m_b.
eps – Precision of approximation.

Returns:

TuckerMatrix representation of the provided dense tensor.

Riemannian #

class tucker_riemopt.sf_tucker.riemannian.TangentVector(manifold_point, delta_core: None | Tensor = None, delta_regular_factors: None | Tensor = None, delta_shared_factor: None | Tensor = None)#

Special representation for tangent vectors of some point from the manifold.

Parameters:

point – Point from the manifold of tensors of fixed SFT rank.
delta_core – Tangent vector delta core.
delta_regular_factors – Tangent vector delta regular factors.
delta_shared_factor – Tangent vector delta shared factors.

construct()#

Build SFTucker tensor from TangentVector representation with at most twice bigger rank.

Returns:: SFTucker tensor.

static group_cores(corner_core, padding_core)#

Combine point’s core and delta core into unite core of tangent vector.

Parameters:

corner_core – Corner block of the grouped core.
padding_core – Adjacent block of the grouped core.

Returns:

Grouped core.

norm()#

Norm of tangent vector. This method is not differentiable as applies series of QR decompositions.

Returns:: Frobenius norm of tangent vector.

tucker_riemopt.sf_tucker.riemannian.grad(f: Callable[[SFTucker], float], X: SFTucker, retain_graph=False) → Tuple[TangentVector, float]#

Compute the Riemannian gradient of the smooth scalar valued function f at point X. The result is the tangent vector of X. Also returns value f(X).

Parameters:

f – Smooth scalar valued function.
X – Point from the manifold.
retain_graph – Optional argument, which may be provided to autodiff framework (e.g. pytorch).

Returns:

A tangent vector of X which is the Riemannian gradient of f and value f(X).

tucker_riemopt.sf_tucker.riemannian.project(X: SFTucker, xi: SFTucker, retain_graph=False) → TangentVector#

Project xi onto the tangent space of X.

Parameters:

X – Point from the manifold.
xi – Arbitrary tensor represented in SF-Tucker format.

Returns:

Result of projection of xi onto the tangent space of X.

API

Contents