TensorFox 1.2.2__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,386 @@
1
+ """
2
+ Initialization Module
3
+ ===================
4
+ Module responsible for constructing the initializations, that is, the initial factor matrices.
5
+ """
6
+
7
+ # Python modules
8
+ import numpy as np
9
+ from numpy import dot, empty, zeros, ones, int64, arange, sqrt, inf, argmax, array, unravel_index
10
+ from numpy.linalg import norm
11
+ from numpy.random import randn, randint
12
+ import sys
13
+ from numba import njit
14
+
15
+ # Tensor Fox modules
16
+ import TensorFox.Conversion as cnv
17
+ import TensorFox.MultilinearAlgebra as mlinalg
18
+
19
+
20
+ def starting_point(T, Tsize, S, U, R, ordering, options):
21
+ """
22
+ This function generates a starting point to begin the iterations. There are four options:
23
+ 1) list: the user may give a list with the factor matrices to be used as starting point.
24
+ 2) 'random': the entries the factor matrices are generated by the normal distribution with mean 0 and variance 1.
25
+ 3) 'smart_random': generates a random starting point with a method based on the MLSVD which always guarantee a
26
+ small relative error. Check the function 'smart_random' for more details about this method.
27
+ 4) 'smart': works similar as the smart_random method, but this one is deterministic and generates the best rank-R
28
+ approximation based on the MLSVD.
29
+
30
+ Inputs
31
+ ------
32
+ T: float array
33
+ Tsize: float
34
+ S: float array
35
+ The core tensor of the MLSVD of T.
36
+ U: list of float 2D arrays
37
+ Each element of U is a orthogonal matrix of the MLSVD of T.
38
+ R: int
39
+ the desired rank.
40
+ ordering: list of ints
41
+ Since the cpd may change the index ordering, this list may be necessary if the user gives an initialization,
42
+ which will be based on the original ordering.
43
+ options: class
44
+
45
+ Outputs
46
+ -------
47
+ init_factors: list of float 2D arrays
48
+ """
49
+
50
+ # Extract all variable from the class of options.
51
+ initialization = options.initialization
52
+ c = options.factors_norm
53
+ symm = options.symm
54
+ display = options.display
55
+ dims = S.shape
56
+ L = len(dims)
57
+
58
+ if type(initialization) == list:
59
+ init_factors = [dot(U[l].T, initialization[ordering[l]]) for l in range(L)]
60
+
61
+ elif initialization == 'random':
62
+ init_factors = [randn(dims[l], R) for l in range(L)]
63
+
64
+ elif initialization == 'smart_random':
65
+ init_factors = smart_random(S, dims, R)
66
+
67
+ elif initialization == 'smart':
68
+ init_factors = smart(S, dims, R)
69
+
70
+ else:
71
+ sys.exit('Error with init parameter initialization.')
72
+
73
+ if type(initialization) != list:
74
+
75
+ # Depending on the tensor, the factors may have null entries. We want to avoid that. The solution is to
76
+ # introduce a very small random noise.
77
+ init_factors = clean_zeros(init_factors, dims, R)
78
+
79
+ # Make all factors balanced.
80
+ init_factors = cnv.equalize(init_factors, R)
81
+
82
+ # Apply additional transformations if requested.
83
+ init_factors = cnv.transform(init_factors, symm, c)
84
+
85
+ if display > 2 or display < -1:
86
+ S_init = cnv.cpd2tens(init_factors)
87
+ if type(T) == list:
88
+ rel_error = mlinalg.compute_error(T, Tsize, S_init, U, dims)
89
+ else:
90
+ S1_init = cnv.unfold(S_init, 1)
91
+ rel_error = mlinalg.compute_error(T, Tsize, S1_init, U, dims)
92
+ return init_factors, rel_error
93
+
94
+ return init_factors
95
+
96
+
97
+ def smart_random(S, dims, R):
98
+ """
99
+ This function generates 1 + int(sqrt(prod(dims))) samples of random possible initializations. The closest to S is
100
+ saved. This method draws R random points in S and generates a tensor with rank <= R from them. The distribution is
101
+ such that it tries to maximize the energy of the sampled tensor, so the error is minimized.
102
+
103
+ Inputs
104
+ ------
105
+ S: float array
106
+ The core tensor of the MLSVD of T.
107
+ dims: list or tuple
108
+ The dimensions (shape) of S.
109
+ R: int
110
+ The desired rank.
111
+
112
+ Outputs
113
+ -------
114
+ best_factors: list of float 2D arrays
115
+ """
116
+
117
+ # Initialize auxiliary values and arrays.
118
+ dims = array(dims)
119
+ samples = 1 + int(sqrt(mlinalg.multiply_dims(dims)))
120
+ best_error = inf
121
+ S1 = cnv.unfold(S, 1)
122
+ Ssize = norm(S)
123
+
124
+ # Start search for a good initial point.
125
+ for sample in range(samples):
126
+ init_factors = smart_sample(S, dims, R)
127
+ # Compute error.
128
+ S1_init = empty(S1.shape)
129
+ S1_init = cnv.cpd2unfold1(S1_init, init_factors)
130
+ rel_error = norm(S1 - S1_init) / Ssize
131
+ if rel_error < best_error:
132
+ best_error = rel_error
133
+ best_factors = init_factors.copy()
134
+
135
+ return best_factors
136
+
137
+
138
+ def smart_sample(S, dims, R):
139
+ """
140
+ We consider a distribution that gives more probability to smaller coordinates. This is because these are associated
141
+ with more energy. As example, let S be a third order tensor of dimensions R1, R2, R3. First the program takes a
142
+ random number c1 in the integer interval [0, R1 + (R1-1) + (R1-2) + ... + 1]. If 0 <= c1 < R1, then it takes i = 1,
143
+ and if R1 <= c1 < R1 + (R1-1), it takes i = 2, and so on. The same goes for the other coordinates.
144
+ Let S_{i_r,j_r,k_r}, r = 1...R, be the points chosen by this method. With them we can form the tensor
145
+ S_init = sum_{r=1}^R S_{i_r,j_r,k_r} e_{i_r} ⊗ e_{j_r} ⊗ e_{k_r}, which should be close to S.
146
+
147
+ Inputs
148
+ ------
149
+ S: float array
150
+ dims: list or tuple
151
+ R: int
152
+
153
+ Ouputs
154
+ ------
155
+ init_factors: list of float 2D arrays
156
+ """
157
+
158
+ L = len(dims)
159
+
160
+ # Initialize arrays to construct initial approximate CPD.
161
+ init_factors = [zeros((dims[l], R)) for l in range(L)]
162
+
163
+ # Construct the upper bounds of the intervals.
164
+ arr = [dims[l] * ones(dims[l]) - arange(dims[l]) for l in range(L)]
165
+ high = [np.sum(arr[l]) for l in range(L)]
166
+
167
+ # Arrays with all random choices.
168
+ C = [randint(high[l], size=R) for l in range(L)]
169
+
170
+ # Update arrays based on the choices made.
171
+ for r in range(R):
172
+ init_factors, idx = assign_values(init_factors, dims, C, arr, r)
173
+ init_factors[0][idx[0], r] = S[tuple(idx)]
174
+
175
+ return init_factors
176
+
177
+
178
+ @njit(nogil=True)
179
+ def assign_values(init_factors, dims, C, arr, r):
180
+ """
181
+ For each r = 1...R, this function constructs l-th one rank term in the CPD of the initialization tensor. For a third
182
+ order tensor the rank one terms are of the form S[i,j,k]*e_i ⊗ e_j ⊗ e_k for some i,j,k choose through the random
183
+ distribution described earlier.
184
+ """
185
+
186
+ L = len(dims)
187
+ idx = []
188
+
189
+ for l in range(L):
190
+ for i in range(dims[l]):
191
+ if (np.sum(arr[l][0: i]) <= C[l][r]) and (C[l][r] < np.sum(arr[l][0: i + 1])):
192
+ init_factors[l][i, r] = 1
193
+ idx.append(i)
194
+ break
195
+
196
+ return init_factors, idx
197
+
198
+
199
+ def smart(S, dims, R):
200
+ """
201
+ Construct a truncated version of S with the R entries with higher energy. For example consider a third order tensor
202
+ S = sum_{i,j,k} S_{i,j,k} * e_{i_r} ⊗ e_{j_r} ⊗ e_{k_r}. First the program takes R coordinates S_{i,j,k} with the
203
+ higher magnitudes and constructs the tensor S_init = sum_{r=1}^r S_{i_r,j_r,k_r} e_{i_r} ⊗ e_{j_r} ⊗ e_{k_r}, which
204
+ should be close to S. Then it verifies if it is possible to reduce the number of rank 1 terms (this is possible just
205
+ by verifying the indexes). In the positive case it is possible to add more entries, hence producing a tensor even
206
+ closer to S.
207
+
208
+ Inputs
209
+ ------
210
+ S: float array
211
+ dims: list or tuple
212
+ R: int
213
+
214
+ Outputs
215
+ -------
216
+ init_factors: list of float 2D arrays
217
+ """
218
+
219
+ L = len(dims)
220
+ S_cp = np.abs(S).copy()
221
+ idx = []
222
+ modes = zeros(R, dtype=int64)
223
+
224
+ # Put entries of S in decreasing order on the energy.
225
+ for i in range(S.size):
226
+ idx.append(unravel_index(argmax(S_cp), S_cp.shape))
227
+ S_cp[idx[i]] = -inf
228
+
229
+ final_idx = idx[:R].copy()
230
+ idx = idx[R:]
231
+
232
+ # Initialize the factors.
233
+ init_factors = [zeros((dims[l], R)) for l in range(L)]
234
+
235
+ previous_count = 0
236
+
237
+ for i in range(100):
238
+ # Try to reduce number of rank 1 terms.
239
+ count, joined = join_rank1(final_idx)
240
+
241
+ # The counting process considers the previous matches and adds the new ones.
242
+ # We discount the previous and only update if there is some new match.
243
+ if count - previous_count <= 0:
244
+ break
245
+
246
+ # There are 'count' rank 1 terms to be included.
247
+ final_idx = final_idx + idx[:count - previous_count]
248
+ idx = idx[count - previous_count:]
249
+ previous_count = count
250
+
251
+ rank1_idx = [[] for r in range(R)]
252
+ r = 0
253
+ for x in joined:
254
+ for y in x:
255
+ rank1_idx[r].append(y)
256
+ final_idx.remove(y)
257
+ r += 1
258
+
259
+ for x in final_idx:
260
+ rank1_idx[r].append(x)
261
+ r += 1
262
+
263
+ # Initialize the factors.
264
+ init_factors = [zeros((dims[l], R)) for l in range(L)]
265
+
266
+ # Use the entries computed previously to generates the factors.
267
+ for r in range(R):
268
+ modes[r] = find_pivot(rank1_idx[r])
269
+ for x in rank1_idx[r]:
270
+ for l in range(L):
271
+ if l == modes[r]:
272
+ init_factors[l][x[l], r] += S[x]
273
+ else:
274
+ init_factors[l][x[l], r] = 1
275
+
276
+ return init_factors
277
+
278
+
279
+ def join_rank1(idx):
280
+ """
281
+ This function verifies if the indexes of S_init (in th smart function) permit to reduce the number of rank 1 terms.
282
+ For example, consider the tensor e_1 ⊗ e_1 ⊗ e_1 + e_1 ⊗ e_2 ⊗ e_1 + e_1 ⊗ e_3 ⊗ e_1 + e_2 ⊗ e_2 ⊗ e_2. From this
283
+ tensor the function join_rank1 will produce the list final_joined = [ [(1,1,1), (1,2,1), (1,3,1)], [(2,2,2)] ],
284
+ meaning that the first list in final_joined are tensor products which can be reduced to a single rank 1 term,
285
+ whereas the second list (which is a singleton) cannot.
286
+
287
+ Inputs
288
+ ------
289
+ idx: list of tuples
290
+ Each element of idx is a tuple of with a single index of S. These tuples are ordered in descending order, such
291
+ that the first ones correspond to the entries of S with higher magnitude.
292
+
293
+ Outputs
294
+ -------
295
+ count: int
296
+ Number of new entries of S included. Originally we only have R entries.
297
+ final_joined: list of list of tuples
298
+ Each element of final_joined is a list with the indexes of a single rank one term.
299
+ """
300
+
301
+ R = len(idx)
302
+ L = len(idx[0])
303
+ count = 0
304
+ tmp = idx.copy()
305
+ joined = [[] for i in range(L*R)]
306
+ i = 0
307
+
308
+ for l in range(L):
309
+ indexes = [j for j in range(L) if j != l]
310
+ r = 0
311
+
312
+ while r < len(tmp):
313
+ # Extract all entries of idx[r] except the l-th one.
314
+ term = tuple(tmp[r][j] for j in indexes)
315
+ rr = r+1
316
+
317
+ while rr < len(tmp):
318
+ term_tmp = tuple(tmp[rr][j] for j in indexes)
319
+ if term_tmp == term:
320
+ joined[i].append(tmp[rr])
321
+ tmp.remove(tmp[rr])
322
+ count += 1
323
+ rr += 1
324
+
325
+ if len(joined[i]) > 0:
326
+ joined[i].append(tmp[r])
327
+ tmp.remove(tmp[r])
328
+
329
+ i += 1
330
+ r += 1
331
+
332
+ final_joined = [joined[i] for i in range(L*R) if len(joined[i]) > 0]
333
+
334
+ return count, final_joined
335
+
336
+
337
+ def find_pivot(x):
338
+ """
339
+ Finds the pivot of a list of indexes computed in the function join_rank1. For example, consider the tensor
340
+ e_1 ⊗ e_1 ⊗ e_1 + e_1 ⊗ e_2 ⊗ e_1 + e_1 ⊗ e_3 ⊗ e_1 + e_2 ⊗ e_2 ⊗ e_2. From this tensor the function join_rank1 will
341
+ produce the list final_joined = [ [(1,1,1), (1,2,1), (1,3,1)], [(2,2,2)] ], meaning that the first list in
342
+ final_joined are tensor products which can be reduced to a single rank 1 term, whereas the second list
343
+ (which is a singleton) cannot. Let x = [(1,1,1), (1,2,1), (1,3,1)]. Then find_pivot(x) = 1, because this is the
344
+ coordinate which is varying while the other are fixed (we could write [1, j, 1] for j=1,2,3 to represent x). Hence
345
+ this is the pivot coordinate.
346
+ Finding indexes with a single pivot coordinate matter because they translate from indexes to rank 1 terms. In the
347
+ example above we can, informally, write (1,1,1) + (1,2,1) + (1,3,1) = (1, 1+2+3, 1), meaning that
348
+ e_1 ⊗ e_1 ⊗ e_1 + e_1 ⊗ e_2 ⊗ e_1 + e_1 ⊗ e_3 ⊗ e_1 = e_1 ⊗ (e_1 + e_2 + e_3) ⊗ e_1.
349
+ """
350
+
351
+ if len(x) == 1:
352
+ return 0
353
+
354
+ x1 = x[0]
355
+ x2 = x[1]
356
+ for l in range(len(x1)):
357
+ if x1[l] != x2[l]:
358
+ return l
359
+
360
+
361
+ def clean_zeros(init_factors, dims, R):
362
+ """
363
+ Any null entry is redefined to be a small random number.
364
+ """
365
+
366
+ # Initialize the factors X, Y, Z with small noises to avoid null entries.
367
+ L = len(dims)
368
+
369
+ for l in range(L):
370
+ init_factors[l] = clean_mode_l(init_factors[l], dims[l], R)
371
+
372
+ return init_factors
373
+
374
+
375
+ @njit(nogil=True)
376
+ def clean_mode_l(factor, dim, R):
377
+ """
378
+ Performs the cleaning stage for mode l.
379
+ """
380
+
381
+ for i in range(dim):
382
+ for r in range(R):
383
+ if factor[i, r] == 0.0:
384
+ factor[i, r] = 1e-4 * randn() * norm(factor)
385
+
386
+ return factor