def cpd(T, R, options=False):
"""
Given a tensor T and a rank R, this function computes an approximated CPD of T with rank r. The factors matrices are
given in the form of a list [W^(1),...,W^(L)]. They are such that sum_(r=1)^R W[:,r]^(1) ⊗ ... ⊗ W[:,r]^(L) is an
approximation for T, where W[:,r]^(l) denotes the r-th column of W^(l). The same goes for the other factor matrices.
Inputs
------
T: float array
Objective tensor in coordinates.
R: int
The desired rank of the approximating tensor.
options: class with the following parameters
maxiter: int
Number of maximum iterations allowed for the dGN function. Default is 200.
tol, tol_step, tol_improv, tol_grad: float
Tolerance criterion to stop the iteration process of the dGN function. Default is 1e-6 for all. Let T^(k) be
the approximation at the k-th iteration, with corresponding CPD w^(k) in vectorized form. The program stops
if
1) |T - T^(k)| / |T| < tol
2) | w^(k-1) - w^(k) | < tol_step
3) | |T - T^(k-1)| / |T| - |T - T^(k)| / |T| | < tol_improv
4) | grad F(w^(k)) | < tol_grad, where F(w^(k)) = 1/2 |T - T^(k)|^2
tol_mlsvd: float
Tolerance criterion for the truncation. The idea is to obtain a truncation (U_1,...,U_L)*S such that
|T - (U_1,...,U_L)*S| / |T| < tol_mlsvd. Default is 1e-16. If tol_mlsvd = -1 the program uses the original
tensor, so the computation of the MLSVD is not performed.
trunc_dims: int or list of ints
Consider a third order tensor T. If trunc_dims is not 0, then it should be a list with three integers
[R1,R2,R3] such that 1 <= R1 <= m, 1 <= R2 <= n, 1 <= R3 <= p. The compressed tensor will have dimensions
(R1,R2,R3). Default is 0, which means 'automatic' truncation.
initialization: string or list
This options is used to choose the initial point to start the iterations. For more information, check the
function starting_point.
refine: bool
If True, after the dGN iterations the program uses the solution to repeat the dGN over the original space
using the solution as starting point. Default is False.
symm: bool
The user should set symm to True if the objective tensor is symmetric, otherwise symm is False. Default is
False.
trials: int
This parameter is only used for tensor with order higher than 3. The computation of the tensor train CPD
requires the computation of several CPD of third order tensors. If only one of these CPD's is of low
quality (divergence or local minimum) then all effort is in vain. One work around is to compute several
CPD'd and keep the best, for third order tensor. The parameter trials defines the maximum number of
times we repeat the computation of each third order CPD. These trials stops when the relative error is
less than 1e-4 or when the maximum number of trials is reached. Default is trials=1.
display: -2, -1, 0, 1, 2, 3 or 4
This options is used to control how information about the computations are displayed on the screen. The
possible values are -1, 0, 1 (default), 2, 3, 4. Notice that display=3 makes the overall running time large
since it will force the program to show intermediate errors which are computationally costly. -1 is a
special option for displaying minimal relevant information for tensors with order higher then 3. We
summarize the display options below.
-2: display same as options -1 plus the Tensor Train error
-1: display only the errors of each CPD computation and the final relevant information
0: no information is printed
1: partial information is printed
2: full information is printed
3: full information + errors of truncation and starting point are printed
4: almost equal to display = 3 but now there are more digits displayed on the screen (display = 3 is a
"cleaner" version of display = 4, with less information).
epochs: int
Number of Tensor Train CPD cycles. Use only for tensor with order higher than 3. Default is epochs=1.
It is not necessary to create 'options' with all parameters described above. Any missing parameter is assigned to
its default value automatically. For more information about the options, check the Tensor Fox tutorial at
https://github.com/felipebottega/Tensor-Fox/tree/master/tutorial
Outputs
-------
factors: list of float 2D arrays with shape (dims[i], R) each
The factors matrices which corresponds to an approximate CPD for T.
final_outputs: list of classes
Each tricpd and bicpd call gives a output class with all sort of information about the computations. The list
'final_outputs' contains all these classes.
"""
# INITIAL PREPARATIONS
# Verify if T is sparse, in which case it will be given as a list with the data.
if type(T) == list:
T_orig = deepcopy(T)
T = deepcopy(T_orig)
data_orig, idxs_orig, dims_orig = T_orig
else:
dims_orig = T.shape
L = len(dims_orig)
# Set options.
options = aux.make_options(options, L)
method = options.method
display = options.display
tol_mlsvd = options.tol_mlsvd
if type(tol_mlsvd) == list:
if L > 3:
tol_mlsvd = tol_mlsvd[0]
else:
tol_mlsvd = tol_mlsvd[1]
# Test consistency of dimensions and rank.
aux.consistency(R, dims_orig, options)
# Verify method.
if method == 'dGN' or method == 'als':
factors, output = tricpd(T, R, options)
return factors, output
# Change ordering of indexes to improve performance if possible.
T, ordering = aux.sort_dims(T)
if type(T) == list:
Tsize = norm(T[0])
dims = T[2]
# If T is sparse, we must use the classic method, and tol_mlsvd is set to the default 1e-16 in the case the
# user requested -1 or 0.
if tol_mlsvd < 0:
options.tol_mlsvd = 1e-16
tol_mlsvd = 1e-16
else:
Tsize = norm(T)
dims = T.shape
# COMPRESSION STAGE
if display != 0:
print(
'-----------------------------------------------------------------------------------------------'
)
print('Computing MLSVD')
# Compute compressed version of T with the MLSVD. We have that T = (U_1,...,U_L)*S.
if display > 2 or display < -1:
S, U, T1, sigmas, best_error = cmpr.mlsvd(T, Tsize, R, options)
else:
S, U, T1, sigmas = cmpr.mlsvd(T, Tsize, R, options)
if display != 0:
if prod(array(S.shape) == array(dims)):
if tol_mlsvd == -1:
print(' No compression and no truncation requested by user')
print(' Working with dimensions', dims)
else:
print(' No compression detected')
print(' Working with dimensions', dims)
else:
print(' Compression detected')
print(' Compressing from', dims, 'to', S.shape)
if display > 2 or display < -1:
print(' Compression relative error = {:7e}'.format(best_error))
print()
# Increase dimensions if r > min(S.shape).
S_orig_dims = S.shape
if R > min(S_orig_dims):
inflate_status = True
S = cnv.inflate(S, R, S_orig_dims)
else:
inflate_status = False
# For higher order tensors the trunc_dims options is only valid for the original tensor and its MLSVD.
options.trunc_dims = 0
# TENSOR TRAIN AND DAMPED GAUSS-NEWTON STAGE
factors, outputs = highcpd(S, R, options)
factors = cnv.deflate(factors, S_orig_dims, inflate_status)
# Use the orthogonal transformations to work in the original space.
for l in range(L):
factors[l] = dot(U[l], factors[l])
# FINAL WORKS
# Compute error.
if type(T1) == ndarray:
T1_approx = empty(T1.shape)
T1_approx = cnv.cpd2unfold1(T1_approx, factors)
rel_error = crt.fastnorm(T1, T1_approx) / Tsize
# Go back to the original dimension ordering.
factors = aux.unsort_dims(factors, ordering)
else:
# Go back to the original dimension ordering.
factors = aux.unsort_dims(factors, ordering)
rel_error = crt.sparse_fastnorm(data_orig, idxs_orig, dims_orig,
factors) / Tsize
num_steps = 0
for output in outputs:
num_steps += output.num_steps
accuracy = max(0, 100 * (1 - rel_error))
if options.display != 0:
print()
print(
'==============================================================================================='
)
print(
'==============================================================================================='
)
print('Final results')
print(' Number of steps =', num_steps)
print(' Relative error =', rel_error)
acc = float('%.6e' % Decimal(accuracy))
print(' Accuracy = ', acc, '%')
final_outputs = aux.make_final_outputs(num_steps, rel_error, accuracy,
outputs, options)
return factors, final_outputs
def tricpd(T, R, options):
"""
Given a tensor T and a rank R, this function computes an approximated CPD of T with rank R. This function is called
when the user sets method = 'dGN'.
Inputs
------
T: float array
R: int
options: class
Outputs
-------
factors: list of float 2D arrays
output: class
This class contains all information needed about the computations made. We summarize these information below.
num_steps: the total number of steps (iterations) the dGN function used at the two runs.
accuracy: the accuracy of the solution, which is defined by the formula 100*(1 - rel_error). 0 means 0% of
accuracy (worst case) and 100 means 100% of accuracy (best case).
rel_error: relative error |T - T_approx|/|T| of the approximation computed.
step_sizes: array with the distances between consecutive computed points at each iteration.
errors: array with the absolute errors of the approximating tensor at each iteration.
improv: array with the differences between consecutive absolute errors.
gradients: array with the gradient of the error function at each iteration. We expect that these gradients
converges to zero as we keep iterating since the objective point is a local minimum.
stop: it is a list of two integers. The first integer indicates why the dGN stopped at the first run, and
the second integer indicates why the dGN stopped at the second run (refinement stage). Check the
functions mlsvd and dGN for more information.
"""
# INITIALIZE RELEVANT VARIABLES
# Verify if T is sparse, in which case it will be given as a list with the data.
if type(T) == list:
T_orig = deepcopy(T)
T = deepcopy(T_orig)
dims_orig = T_orig[2]
else:
dims_orig = T.shape
L = len(dims_orig)
# Set options.
initialization = options.initialization
refine = options.refine
symm = options.symm
display = options.display
tol_mlsvd = options.tol_mlsvd
method = options.method
if type(tol_mlsvd) == list:
tol_mlsvd = tol_mlsvd[0]
# Change ordering of indexes to improve performance if possible.
T, ordering = aux.sort_dims(T)
if type(T) == list:
Tsize = norm(T[0])
dims = T[2]
# If T is sparse, we must use the classic method, and tol_mlsvd is set to the default 1e-16 in the case the
# user requested -1 or 0.
if tol_mlsvd < 0:
tol_mlsvd = 1e-16
if type(tol_mlsvd) == list:
options.tol_mlsvd[0] = 1e-16
else:
options.tol_mlsvd = 1e-16
else:
Tsize = norm(T)
dims = T.shape
# COMPRESSION STAGE
if display > 0:
print(
'-----------------------------------------------------------------------------------------------'
)
print('Computing MLSVD')
# Compute compressed version of T with the MLSVD. We have that T = (U_1, ..., U_L)*S.
if display > 2 or display < -1:
S, U, T1, sigmas, best_error = cmpr.mlsvd(T, Tsize, R, options)
else:
S, U, T1, sigmas = cmpr.mlsvd(T, Tsize, R, options)
dims_cmpr = S.shape
# When the tensor is symmetric we want S to have equal dimensions.
if symm:
R_min = min(dims_cmpr)
dims_cmpr = [R_min for l in range(L)]
dims_cmpr_slices = tuple(slice(R_min) for l in range(L))
S = S[dims_cmpr_slices]
U = [U[l][:, :R_min] for l in range(L)]
if display > 0:
if dims_cmpr == dims:
if tol_mlsvd == -1:
print(' No compression and no truncation requested by user')
print(' Working with dimensions', dims)
else:
print(' No compression detected')
print(' Working with dimensions', dims)
else:
print(' Compression detected')
print(' Compressing from', dims, 'to', S.shape)
if display > 2:
print(' Compression relative error = {:7e}'.format(best_error))
# GENERATION OF STARTING POINT STAGE
# Generate initial to start dGN.
if display > 2 or display < -1:
init_factors, init_error = init.starting_point(T, Tsize, S, U, R,
ordering, options)
else:
init_factors = init.starting_point(T, Tsize, S, U, R, ordering,
options)
if display > 0:
print(
'-----------------------------------------------------------------------------------------------'
)
if type(initialization) == list:
print('Type of initialization: user')
else:
print('Type of initialization:', initialization)
if display > 2:
print(
' Initial guess relative error = {:5e}'.format(init_error))
# DAMPED GAUSS-NEWTON STAGE
if display > 0:
print(
'-----------------------------------------------------------------------------------------------'
)
print('Computing CPD')
# Compute the approximated tensor in coordinates with dGN or ALS.
if method == 'als':
factors, step_sizes_main, errors_main, improv_main, gradients_main, stop_main = \
als.als(S, init_factors, R, options)
else:
factors, step_sizes_main, errors_main, improv_main, gradients_main, stop_main = \
gn.dGN(S, init_factors, R, options)
# Use the orthogonal transformations to work in the original space.
for l in range(L):
factors[l] = dot(U[l], factors[l])
# REFINEMENT STAGE
# If T is sparse, no refinement is made.
if type(T) == list:
refine = False
if refine:
if display > 0:
print()
print(
'==============================================================================================='
)
print('Computing refinement of solution')
if display > 2:
T1_approx = empty(T1.shape)
T1_approx = cnv.cpd2unfold1(T1_approx, factors)
init_error = crt.fastnorm(T1, T1_approx) / Tsize
print(
' Initial guess relative error = {:5e}'.format(init_error))
if display > 0:
print(
'-----------------------------------------------------------------------------------------------'
)
print('Computing CPD')
if method == 'als':
factors, step_sizes_refine, errors_refine, improv_refine, gradients_refine, stop_refine = \
als.als(T, factors, R, options)
else:
factors, step_sizes_refine, errors_refine, improv_refine, gradients_refine, stop_refine = \
gn.dGN(T, factors, R, options)
else:
step_sizes_refine = array([0])
errors_refine = array([0])
improv_refine = array([0])
gradients_refine = array([0])
stop_refine = 8
# FINAL WORKS
# Compute error.
if type(T1) == ndarray:
T1_approx = empty(T1.shape)
T1_approx = cnv.cpd2unfold1(T1_approx, factors)
# Go back to the original dimension ordering.
factors = aux.unsort_dims(factors, ordering)
# Save and display final informations.
output = aux.output_info(T1, Tsize, T1_approx, step_sizes_main,
step_sizes_refine, errors_main, errors_refine,
improv_main, improv_refine, gradients_main,
gradients_refine, stop_main, stop_refine,
options)
else:
# Go back to the original dimension ordering.
factors = aux.unsort_dims(factors, ordering)
# Save and display final informations.
output = aux.output_info(T_orig, Tsize, factors, step_sizes_main,
step_sizes_refine, errors_main, errors_refine,
improv_main, improv_refine, gradients_main,
gradients_refine, stop_main, stop_refine,
options)
if display > 0:
print(
'==============================================================================================='
)
print('Final results')
if refine:
print(' Number of steps =', output.num_steps)
else:
print(' Number of steps =', output.num_steps)
print(' Relative error =', output.rel_error)
acc = float('%.6e' % Decimal(output.accuracy))
print(' Accuracy = ', acc, '%')
return factors, output