# Cp tensor#

class ivy.data_classes.factorized_tensor.cp_tensor.CPTensor(cp_tensor)[source]#
__init__(cp_tensor)[source]#
_abc_impl = <_abc._abc_data object>#
cp_copy()[source]#
static cp_flip_sign(cp_tensor, mode=0, func=None)[source]#

Return cp_tensor with factors flipped to have positive signs. The sign of a given column is determined by func, which is the mean by default. Any negative signs are assigned to the mode indicated by mode.

Parameters:
• cp_tensor

CPTensor = (weight, factors) factors is list of matrices, all with the same number of columns i.e.:

for u in U:
u[i].shape == (s_i, R)


where R is fixed while s_i can vary with i

• mode (default: 0) – mode that should receive negative signs

• func (default: None) – a function that should summarize the sign of a column it must be able to take an axis argument

Returns:

CPTensor = (normalisation_weights, normalised_factors)

Compute (for a third-order tensor)

$\begin{split}\nabla 0.5 ||\\mathcal{X} - [\\mathbf{w}; \\mathbf{A}, \\mathbf{B}, \\mathbf{C}]||^2\end{split}$

where $$[\\mathbf{w}; \\mathbf{A}, \\mathbf{B}, \\mathbf{C}]$$ is the CP decomposition with weights $$\\mathbf{w}$$ and factor matrices $$\\mathbf{A}$$, $$\\mathbf{B}$$ and $$\\mathbf{C}$$. Note that this does not return the gradient with respect to the weights even if CP is normalized.

Parameters:
• cp_tensor – CPTensor = (weight, factors) factors is a list of factor matrices, all with the same number of columns i.e. for all matrix U in factor_matrices: U has shape (s_i, R), where R is fixed and s_i varies with i

• mask (default: None) – A mask to be applied to the final tensor. It should be broadcastable to the shape of the final tensor, that is (U[1].shape[0], ... U[-1].shape[0]).

• return_loss (default: False) – Optionally return the scalar loss function along with the gradient.

Returns:

• cp_gradient (CPTensor = (None, factors)) – factors is a list of factor matrix gradients, all with the same number of columns i.e. for all matrix U in factor_matrices: U has shape (s_i, R), where R is fixed and s_i varies with i

• loss (float) – Scalar quantity of the loss function corresponding to cp_gradient. Only returned if return_loss = True.

static cp_mode_dot(cp_tensor, matrix_or_vector, mode, keep_dim=False, copy=False)[source]#

N-mode product of a CP tensor and a matrix or vector at the specified mode.

Parameters:
• cp_tensor – ivy.CPTensor or (core, factors)

• matrix_or_vector – 1D or 2D array of shape (J, i_k) or (i_k, ) matrix or vectors to which to n-mode multiply the tensor

• mode (int) –

Returns:

CPTensor = (core, factors)mode-mode product of tensor by matrix_or_vector * of shape $$(i_1, ..., i_{k-1}, J, i_{k+1}, ..., i_N)$$

if matrix_or_vector is a matrix

• of shape $$(i_1, ..., i_{k-1}, i_{k+1}, ..., i_N)$$ if matrix_or_vector is a vector

cp_multi_mode_dot

chaining several mode_dot in one call

static cp_n_param(tensor_shape, rank, weights=False)[source]#

Return number of parameters of a CP decomposition for a given rank and full tensor_shape.

Parameters:
• tensor_shape – shape of the full tensor to decompose (or approximate)

• rank – rank of the CP decomposition

Returns:

n_params

Number of parameters of a CP decomposition of rank rank

of a full tensor of shape tensor_shape

static cp_norm(cp_tensor)[source]#

Return the l2 norm of a CP tensor.

Parameters:

cp_tensor – ivy.CPTensor or (core, factors)

Returns:

l2-norm

Notes

This is ||cp_to_tensor(factors)||^2

You can see this using the fact that khatria-rao(A, B)^T x khatri-rao(A, B) = A^T x A * B^T x B

static cp_normalize(cp_tensor)[source]#

Return cp_tensor with factors normalised to unit length.

Turns factors = [|U_1, ... U_n|] into [weights; |V_1, ... V_n|], where the columns of each V_k are normalized to unit Euclidean length from the columns of U_k with the normalizing constants absorbed into weights. In the special case of a symmetric tensor, weights holds the eigenvalues of the tensor.

Parameters:

cp_tensor

factors is list of matrices,

all with the same number of columns

i.e.:

for u in U:
u[i].shape == (s_i, R)


where R is fixed while s_i can vary with i

Returns:

CPTensor = (normalisation_weights, normalised_factors)

Turn the Khatri-product of matrices into a full tensor.

factor_matrices = [|U_1, ... U_n|] becomes a tensor shape (U[1].shape[0], U[2].shape[0], ... U[-1].shape[0])

Parameters:
• cp_tensor – factors is a list of factor matrices, all with the same number of columns i.e. for all matrix U in factor_matrices: U has shape (s_i, R), where R is fixed and s_i varies with i

• mask (default: None) – mask to be applied to the final tensor. It should be broadcastable to the shape of the final tensor, that is (U[1].shape[0], ... U[-1].shape[0]).

Returns:

ivy.Array – full tensor of shape (U[1].shape[0], ... U[-1].shape[0])

Notes

This version works by first computing the mode-0 unfolding of the tensor and then refolding it.

There are other possible and equivalent alternate implementation, e.g. summing over r and updating an outer product of vectors.

static cp_to_unfolded(cp_tensor, mode)[source]#

Turn the khatri-product of matrices into an unfolded tensor.

turns factors = [|U_1, ... U_n|] into a mode-mode unfolding of the tensor

Parameters:
• cp_tensor – factors is a list of matrices, all with the same number of columns ie for all u in factor_matrices: u[i] has shape (s_u_i, R), where R is fixed

• mode – mode of the desired unfolding

Returns:

ivy.Array – unfolded tensor of shape (tensor_shape[mode], -1)

Notes

Writing factors = [U_1, …, U_n], we exploit the fact that U_k = U[k].dot(khatri_rao(U_1, ..., U_k-1, U_k+1, ..., U_n))

static cp_to_vec(cp_tensor)[source]#

Turn the khatri-product of matrices into a vector.

(the tensor factors = [|U_1, ... U_n|] is converted into a raveled mode-0 unfolding)

Parameters:

cp_tensor

factors is a list of matrices, all with the same number of columns i.e.:

for u in U:
u[i].shape == (s_i, R)


where R is fixed while s_i can vary with i

Returns:

ivy.Array – vectorised tensor

mode_dot(matrix_or_vector, mode, keep_dim=False, copy=True)[source]#

N-mode product of a CP tensor and a matrix or vector at the specified mode.

Parameters:
• cp_tensor

• matrix_or_vector – 1D or 2D array of shape (J, i_k) or (i_k, ) matrix or vectors to which to n-mode multiply the tensor

• mode – int

Returns:

CPTensor = (core, factors)mode-mode product of tensor by matrix_or_vector * of shape $$(i_1, ..., i_{k-1}, J, i_{k+1}, ..., i_N)$$

if matrix_or_vector is a matrix

• of shape $$(i_1, ..., i_{k-1}, i_{k+1}, ..., i_N)$$ if matrix_or_vector is a vector

cp_mode_dot

chaining several mode_dot in one call

property n_param#
norm()[source]#

Return the l2 norm of a CP tensor.

Parameters:

cp_tensor – ivy.CPTensor or (core, factors)

Returns:

l2-norm – int

Notes

This is ||cp_to_tensor(factors)||^2

You can see this using the fact that khatria-rao(A, B)^T x khatri-rao(A, B) = A^T x A * B^T x B

normalize(inplace=True)[source]#

Normalize the factors to unit length.

Turns factors = [|U_1, ... U_n|] into [weights; |V_1, ... V_n|], where the columns of each V_k are normalized to unit Euclidean length from the columns of U_k with the normalizing constants absorbed into weights. In the special case of a symmetric tensor, weights holds the eigenvalues of the tensor.

Parameters:
• cp_tensor

CPTensor = (weight, factors) factors is list of matrices, all with the same number of columns i.e.:

for u in U:
u[i].shape == (s_i, R)


where R is fixed while s_i can vary with i

• inplace (default: True) – if False, returns a normalized Copy otherwise the tensor modifies itself and returns itself

Returns:

CPTensor = (normalisation_weights, normalised_factors) – returns itself if inplace is True, a normalized copy otherwise

to_tensor()[source]#
to_unfolded(mode)[source]#
to_vec()[source]#
static unfolding_dot_khatri_rao(x, cp_tensor, mode)[source]#

Mode-n unfolding times khatri-rao product of factors.

Parameters:
• x – tensor to unfold

• factors – list of matrices of which to the khatri-rao product

• mode – mode on which to unfold tensor

Returns:

mttkrp – dot(unfold(x, mode), khatri-rao(factors))

static validate_cp_rank(tensor_shape, rank='same', rounding='round')[source]#

Return the rank of a CP Decomposition.

Parameters:
• tensor_shape – shape of the tensor to decompose

• rank (default: 'same') – way to determine the rank, by default ‘same’ if ‘same’: rank is computed to keep the number of parameters (at most) the same if float, computes a rank so as to keep rank percent of the original number of parameters if int, just returns rank

• rounding (default: 'round') – {‘round’, ‘floor’, ‘ceil’}

Returns:

rank – rank of the decomposition

static validate_cp_tensor(cp_tensor)[source]#

Validate a cp_tensor in the form (weights, factors)

Return the rank and shape of the validated tensor

Parameters:

cp_tensor – CPTensor or (weights, factors)

Returns:

(shape, rank) – size of the full tensor and rank of the CP tensor