tensorly.decomposition.constrained_parafac

constrained_parafac(tensor, rank, n_iter_max=100, n_iter_max_inner=10, init='svd', svd='numpy_svd', tol_outer=1e-08, tol_inner=1e-06, random_state=None, verbose=0, return_errors=False, cvg_criterion='abs_rec_error', fixed_modes=None, non_negative=None, l1_reg=None, l2_reg=None, l2_square_reg=None, unimodality=None, normalize=None, simplex=None, normalized_sparsity=None, soft_sparsity=None, smoothness=None, monotonicity=None, hard_sparsity=None)[source]

CANDECOMP/PARAFAC decomposition via alternating optimization of alternating direction method of multipliers (AO-ADMM):

Computes a rank-rank decomposition of tensor [1] such that:

tensor = [|weights; factors[0], ..., factors[-1] |],

where factors are either penalized or constrained according to the user-defined constraint.

In order to compute the factors efficiently, the ADMM algorithm introduces an auxilliary factor which is called factor_aux in the function.

Parameters
tensorndarray
rankint

Number of components.

n_iter_maxint

Maximum number of iteration for outer loop

n_iter_max_innerint

Number of iteration for inner loop

init{‘svd’, ‘random’, cptensor}, optional

Type of factor matrix initialization. See initialize_factors.

svdstr, default is ‘numpy_svd’

function to use to compute the SVD, acceptable values in tensorly.SVD_FUNS

tol_outerfloat, optional

(Default: 1e-8) Relative reconstruction error tolerance for outer loop. The algorithm is considered to have found a local minimum when the reconstruction error is less than tol_outer.

tol_innerfloat, optional

(Default: 1e-6) Absolute reconstruction error tolerance for factor update during inner loop, i.e. ADMM optimization.

random_state{None, int, np.random.RandomState}
verboseint, optional

Level of verbosity

return_errorsbool, optional

Activate return of iteration errors

non_negativebool or dictionary

This constraint is clipping negative values to ‘0’. If it is True non-negative constraint is applied to all modes.

l1_regfloat or list or dictionary, optional
l2_regfloat or list or dictionary, optional
l2_square_regfloat or list or dictionary, optional
unimodalitybool or dictionary, optional

If it is True unimodality constraint is applied to all modes.

normalizebool or dictionary, optional

This constraint divides all the values by maximum value of the input array. If it is True normalize constraint is applied to all modes.

simplexfloat or list or dictionary, optional
normalized_sparsityfloat or list or dictionary, optional
soft_sparsityfloat or list or dictionary, optional
smoothnessfloat or list or dictionary, optional
monotonicitybool or dictionary, optional
hard_sparsityfloat or list or dictionary, optional
cvg_criterion{‘abs_rec_error’, ‘rec_error’}, optional

Stopping criterion if tol is not None. If ‘rec_error’, algorithm stops at current iteration if (previous rec_error - current rec_error) < tol. If ‘abs_rec_error’, algorithm terminates when |previous rec_error - current rec_error| < tol.

fixed_modeslist, default is None

A list of modes for which the initial value is not modified. The last mode cannot be fixed due to error computation.

Returns
CPTensor(weight, factors)
  • weights : 1D array of shape (rank, )

  • factors : List of factors of the CP decomposition element i is of shape (tensor.shape[i], rank)

errorslist

A list of reconstruction errors at each iteration of the algorithms.

References

1

T.G.Kolda and B.W.Bader, “Tensor Decompositions and Applications”, SIAM REVIEW, vol. 51, n. 3, pp. 455-500, 2009.

2

Huang, Kejun, Nicholas D. Sidiropoulos, and Athanasios P. Liavas. “A flexible and efficient algorithmic framework for constrained matrix and tensor factorization.” IEEE Transactions on Signal Processing 64.19 (2016): 5052-5065.