pyCP_APR.numpy_cp package

Submodules

pyCP_APR.numpy_cp.CP_APR module

Python implementation of the CP-APR algorithm [1-4] with Numpy backend.

This backend can be used to factorize sparse tensorsin COO format and dense Numpy tensors.

References

[1] General software, latest release: Brett W. Bader, Tamara G. Kolda and others, Tensor Toolbox for MATLAB, Version 3.2.1, www.tensortoolbox.org, April 5, 2021.

[2] Dense tensors: B. W. Bader and T. G. Kolda, Algorithm 862: MATLAB Tensor Classes for Fast Algorithm Prototyping, ACM Trans. Mathematical Software, 32(4):635-653, 2006, http://dx.doi.org/10.1145/1186785.1186794.

[3] Sparse, Kruskal, and Tucker tensors: B. W. Bader and T. G. Kolda, Efficient MATLAB Computations with Sparse and Factored Tensors, SIAM J. Scientific Computing, 30(1):205-231, 2007, http://dx.doi.org/10.1137/060676489.

[4] Chi, E.C. and Kolda, T.G., 2012. On tensors, sparsity, and nonnegative factorizations. SIAM Journal on Matrix Analysis and Applications, 33(4), pp.1272-1299.

@author: Maksim Ekin Eren

class pyCP_APR.numpy_cp.CP_APR.CP_APR_MU(epsilon=1e-10, kappa=0.01, kappa_tol=1e-10, max_inner_iters=10, n_iters=1000, print_inner_itn=0, verbose=10, stoptime=1000000.0, tol=0.0001, random_state=42, return_type='numpy')[source]

Bases: object

Initilize the CP_APR_MU class.

Parameters
  • epsilon (float, optional) -- Prevents zero division. Default is 1e-10.

  • kappa (float, optional) -- Fix slackness level. Default is 1e-2.

  • kappa_tol (float, optional) -- Tolerance on complementary slackness. The default is 1e-10.

  • max_inner_iters (int, optional) -- Number of inner iterations per epoch. Default is 10.

  • n_iters (int, optional) -- Number of iterations during optimization or epoch. Default is 1000.

  • print_inner_itn (int, optional) -- Print every n inner iterations. Does not print if 0. Default is 0.

  • verbose (int, optional) -- Print every n epoch, or n_iters. Does not print if 0. Default is 10.

  • stoptime (float, optional) -- Number of seconds before early stopping. Default is 1e6.

  • tol (float, optional) -- KKT violations tolerance. Default is 1e-4.

  • random_state (int, optional) -- Random seed for initial M. The default is 42.

train(tensor=[], coords=[], values=[], rank=2, Minit='random', Type='sptensor')[source]

Factorize the tensor X (i.e. compute the KRUSKAL tensor M).

Parameters
  • tensor (array) --

    Original dense tensor X.

    Use with Type = 'tensor' and pass the tensor parameter as a dense Numpy array.

  • coords (Numpy array (i.e. array that is a list of list)) --

    Array of non-zero coordinates for sparse tensor X. COO format.

    Each entry in this array is a coordinate of a non-zero value in the tensor.

    Used when Type = 'sptensor' and tensor parameter is not passed.

    len(Coords) is number of total entiries in X, and len(coords[0]) should give the number of dimensions.

  • values (Numpy array (i.e. list of non-zero values corresponding to each list of non-zero coordinates)) --

    Array of non-zero tensor entries. COO format.

    Used when Type = 'sptensor' and tensor parameter is not passed.

    Length of values must match the length of coords.

  • rank (int) -- Tensor rank, i.e. number of components to extract. The default is 2.

  • Minit (string or dictionary of latent factors) --

    Initial value of latent factors.

    If Minit = 'random', initial factors are chosen randomly from uniform distribution between 0 and 1.

    Else, pass dictionary where the key is the mode number and value is array size d x r where d is the number of elements on the dimension and r is the rank.

    The default is "random".

  • Type (string) --

    Type of tensor (i.e. sparse or dense).

    Use 'sptensor' for sparse, and 'tensor' for dense tensors.

    If 'sptensor' used, pass the list of non-zero coordinates using the Coords parameter and the corresponding list of non-zero elements with values parameter.

    The default is 'sptensor'.

Returns

result -- KRUSKAL tensor M is returned. The latent factors can be found with the key 'Factors'.

The weight of each component can be found with the key 'Weights'.

Return type

dict

pyCP_APR.numpy_cp.ktensor module

ktensor.py contains the K_TENSOR class for KRUSKAL tensor M object representation.

References

[1] General software, latest release: Brett W. Bader, Tamara G. Kolda and others, Tensor Toolbox for MATLAB, Version 3.2.1, www.tensortoolbox.org, April 5, 2021.

[2] Dense tensors: B. W. Bader and T. G. Kolda, Algorithm 862: MATLAB Tensor Classes for Fast Algorithm Prototyping, ACM Trans. Mathematical Software, 32(4):635-653, 2006, http://dx.doi.org/10.1145/1186785.1186794.

[3] Sparse, Kruskal, and Tucker tensors: B. W. Bader and T. G. Kolda, Efficient MATLAB Computations with Sparse and Factored Tensors, SIAM J. Scientific Computing, 30(1):205-231, 2007, http://dx.doi.org/10.1137/060676489.

[4] Chi, E.C. and Kolda, T.G., 2012. On tensors, sparsity, and nonnegative factorizations. SIAM Journal on Matrix Analysis and Applications, 33(4), pp.1272-1299.

@author: Maksim Ekin Eren

class pyCP_APR.numpy_cp.ktensor.K_TENSOR(Rank, Size, Minit='random', random_state=42, order=- 1, weights=- 1)[source]

Bases: object

Initilize the K_TENSOR class.

Creates the object representation of M.

If initial M is not passed, by default, creates M from uniform distribution.

Parameters
  • Rank (int) -- Tensor rank, i.e. number of components in M.

  • Size (list) -- Shape of the tensor.

  • Minit (string or dictionary of latent factors) --

    Initial value of latent factors.

    If Minit = 'random', initial factors are chosen randomly from uniform distribution between 0 and 1.

    Else, pass dictionary where the key is the mode number and value is array size d x r where d is the number of elements on the dimension and r is the rank.

    The default is "random".

  • random_state (int, optional) -- Random seed for initial M. The default is 42.

  • order (int, optional) -- Currently not used. The default is -1.

  • weights (array, optional) --

    Initial weights of the components.

    If not passed, initial weights are 1.

    The default is -1.

arrange(p=[])[source]

This function arranges the components of KRUSKAL tensor M.

Parameters

p (list, optional) -- permutation. The default is [].

deep_copy_factors()[source]

Creates a deep copy of the latent factors in M.

Returns

factors -- Copy of the latent factors of M.

Return type

dict

double()[source]

This function converts the KTENSOR M to a double array.

Returns

A -- Double array of M.

Return type

array

innerprod(X)[source]

This function takes the inner product of tensor X and KRUSKAL tensor M.

Parameters

X (class) -- Original tensor. sptensor.SP_TENSOR.

Returns

res -- inner product of tensor X and KRUSKAL tensor M.

Return type

array

khatrirao(dims, reverse=True)[source]

KHATRIRAO Khatri-Rao product of matrices. Citation: Mrdmnd. (n.d.). mrdmnd/scikit-tensor. GitHub. https://github.com/mrdmnd/scikit-tensor/blob/master/src/tensor_tools.py.

Parameters
  • dims (list) -- which modes to multiply.

  • reverse (bool, optional) -- When true, product is in reverse order. The default is True.

Raises

ValueError -- Invalid tensors.

Returns

P -- Khatri-Rao product of matrices.

Return type

array

norm()[source]

This function takes the Frobenius norm of a KRUSKAL tensor M.

Returns

nrm -- Frobenius norm of M.

Return type

float

normalize(M, normtype=1, N=- 1, mode=- 1)[source]

This function normalizes the columns of the factor matrices.

Parameters
  • M (object) -- KRUSKAL tensor M class. ktensor.K_TENSOR.

  • normtype (int, optional) -- Determines the type of normalization. The default is 1.

  • N (int, optional) -- Factor matrix number. The default is -1.

  • mode (int, optional) -- Dimension number. The default is -1.

Returns

M -- Normalized KRUSKAL tensor M class. ktensor.K_TENSOR.

Return type

object

permute(order)[source]

This function permutes the dimensions of the KRUSKAL tensor M.

Parameters

order (array) -- Vector order.

redistribute(mode)[source]

This function distributes the weights to a specified dimension or mode.

Parameters

mode (int) -- Dimension number.

pyCP_APR.numpy_cp.sptensor module

sptensor.py contains the SP_TENSOR class which is the object representation of the sparse tensor X in COO format.

References

[1] General software, latest release: Brett W. Bader, Tamara G. Kolda and others, Tensor Toolbox for MATLAB, Version 3.2.1, www.tensortoolbox.org, April 5, 2021.

[2] Dense tensors: B. W. Bader and T. G. Kolda, Algorithm 862: MATLAB Tensor Classes for Fast Algorithm Prototyping, ACM Trans. Mathematical Software, 32(4):635-653, 2006, http://dx.doi.org/10.1145/1186785.1186794.

[3] Sparse, Kruskal, and Tucker tensors: B. W. Bader and T. G. Kolda, Efficient MATLAB Computations with Sparse and Factored Tensors, SIAM J. Scientific Computing, 30(1):205-231, 2007, http://dx.doi.org/10.1137/060676489.

[4] Chi, E.C. and Kolda, T.G., 2012. On tensors, sparsity, and nonnegative factorizations. SIAM Journal on Matrix Analysis and Applications, 33(4), pp.1272-1299.

@author: Maksim Ekin Eren

class pyCP_APR.numpy_cp.sptensor.SP_TENSOR(Coords, Values)[source]

Bases: object

Initilize the SP_TENSOR class.

Sorts the tensor entries.

Parameters
  • Coords (Numpy array (i.e. array that is a list of list)) --

    Array of non-zero coordinates for sparse tensor X. COO format.

    Each entry in this array is a coordinate of a non-zero value in the tensor.

    Used when Type = 'sptensor' and tensor parameter is not passed.

    len(Coords) is number of total entiries in X, and len(coords[0]) should give the number of dimensions.

  • Values (Numpy array (i.e. list of non-zero values corresponding to each list of non-zero coordinates)) --

    Array of non-zero tensor entries. COO format.

    Used when Type = 'sptensor' and tensor parameter is not passed.

    Length of values must match the length of coords.

ttv(vecs)[source]

Tensor times vector for KRUSKAL tensor M.

Parameters

vecs (array) -- coluumn vector.

Returns

c -- product of KRUSKAL tensor X with a (column) vector vecs.

Return type

array

pyCP_APR.numpy_cp.tenmat module

tenmat.py creates a matricized tensor.

References

[1] General software, latest release: Brett W. Bader, Tamara G. Kolda and others, Tensor Toolbox for MATLAB, Version 3.2.1, www.tensortoolbox.org, April 5, 2021.

[2] Dense tensors: B. W. Bader and T. G. Kolda, Algorithm 862: MATLAB Tensor Classes for Fast Algorithm Prototyping, ACM Trans. Mathematical Software, 32(4):635-653, 2006, http://dx.doi.org/10.1145/1186785.1186794.

[3] Sparse, Kruskal, and Tucker tensors: B. W. Bader and T. G. Kolda, Efficient MATLAB Computations with Sparse and Factored Tensors, SIAM J. Scientific Computing, 30(1):205-231, 2007, http://dx.doi.org/10.1137/060676489.

[4] Chi, E.C. and Kolda, T.G., 2012. On tensors, sparsity, and nonnegative factorizations. SIAM Journal on Matrix Analysis and Applications, 33(4), pp.1272-1299.

@author: Maksim Ekin Eren

class pyCP_APR.numpy_cp.tenmat.Tenmat(X, mode)[source]

Bases: object

Create a matricized tensor.

Parameters
  • X (class) -- Original tensor. sptensor.SP_TENSOR or tensor.TENSOR

  • mode (int) -- Dimension number.

pyCP_APR.numpy_cp.tensor module

tensor.py contains the TENSOR class for tensor X object representation.

References

[1] General software, latest release: Brett W. Bader, Tamara G. Kolda and others, Tensor Toolbox for MATLAB, Version 3.2.1, www.tensortoolbox.org, April 5, 2021. [2] Dense tensors: B. W. Bader and T. G. Kolda, Algorithm 862: MATLAB Tensor Classes for Fast Algorithm Prototyping, ACM Trans. Mathematical Software, 32(4):635-653, 2006, http://dx.doi.org/10.1145/1186785.1186794. [3] Sparse, Kruskal, and Tucker tensors: B. W. Bader and T. G. Kolda, Efficient MATLAB Computations with Sparse and Factored Tensors, SIAM J. Scientific Computing, 30(1):205-231, 2007, http://dx.doi.org/10.1137/060676489. [4] Chi, E.C. and Kolda, T.G., 2012. On tensors, sparsity, and nonnegative factorizations. SIAM Journal on Matrix Analysis and Applications, 33(4), pp.1272-1299.

@author: Maksim Ekin Eren

class pyCP_APR.numpy_cp.tensor.TENSOR(Tensor)[source]

Bases: object

Initilize the tensor X class.

Creates the object representation of X.

Parameters

Tensor (array) -- Dense Numpy tensor.

Returns

Return type

None.

permute(order)[source]

This function permutes the dimensions of X.

Parameters

order (array) -- Vector order.

ttv(vecs)[source]

Tensor times vector for KRUSKAL tensor M.

Parameters

vecs (array) -- coluumn vector.

Returns

c -- product of KRUSKAL tensor X with a (column) vector vecs.

Return type

array

Module contents

2021. Triad National Security, LLC. All rights reserved. This program was produced under U.S. Government contract 89233218CNA000001 for Los Alamos National Laboratory (LANL), which is operated by Triad National Security, LLC for the U.S. Department of Energy/National Nuclear Security Administration. All rights in the program are reserved by Triad National Security, LLC, and the U.S. Department of Energy/National Nuclear Security Administration. The Government is granted for itself and others acting on its behalf a nonexclusive, paid-up, irrevocable worldwide license in this material to reproduce, prepare derivative works, distribute copies to the public, perform publicly and display publicly, and to permit others to do so.