Cp tensor

class ivy.data_classes.factorized_tensor.cp_tensor.CPTensor(cp_tensor)

Bases: FactorizedTensor

__init__(cp_tensor)

_abc_impl = <_abc._abc_data object>

cp_copy()

static cp_flip_sign(cp_tensor, mode=0, func=None)

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)

static cp_lstsq_grad(cp_tensor, tensor, return_loss=False, mask=None)

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)

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

See also

cp_multi_mode_dot

chaining several mode_dot in one call

static cp_n_param(tensor_shape, rank, weights=False)

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)

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)

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)

static cp_to_tensor(cp_tensor, mask=None)

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)

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)

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)

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

See also

cp_mode_dot

chaining several mode_dot in one call

property n_param

norm()

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)

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()

to_unfolded(mode)

to_vec()

static unfolding_dot_khatri_rao(x, cp_tensor, mode)

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')

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)

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

This should have hopefully given you an overview of the cp_tensor submodule, if you have any questions, please feel free to reach out on our discord!