net.librec.math.structure

Class SparseTensor

java.lang.Object

net.librec.math.structure.SparseTensor

All Implemented Interfaces:

java.io.Serializable, java.lang.Iterable<TensorEntry>, DataSet

public class SparseTensor
extends java.lang.Object
implements DataSet, java.lang.Iterable<TensorEntry>, java.io.Serializable

Data Structure: Sparse Tensor

For easy documentation, here we use (keys, value) to indicate each entry of a tensor, and index is used to indicate the position in which the entry is stored in the lists.

Reference: Kolda and Bader, Tensor Decompositions and Applications, SIAM REVIEW, Vol. 51, No. 3, pp. 455–500

Author:

Guo Guibing

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
int[]	dimensions
java.util.List<java.lang.Integer>[]	ndKeys
int	numDimensions number of dimensions, i.e., the order (or modes, ways) of a tensor
java.util.List<java.lang.Double>	values

Constructor Summary

Constructors

Constructor and Description
SparseTensor(int... dims) Construct an empty sparse tensor
SparseTensor(int[] dims, java.util.List<java.lang.Integer>[] nds, java.util.List<java.lang.Double> vals) Construct a sparse tensor with indices and values

Method Summary

Methods

Modifier and Type	Method and Description
void	add(double val, int... keys) Add a value to a given i-entry
void	buildIndex(int... dims) build index at dimensions nd
void	buildIndices() build index for all dimensions
SparseTensor	clone() make a deep clone
boolean	contains(int... keys) Check if a given keys exists
int[]	dimensions()
SparseVector	fiber(int dim, int... keys) A fiber is defined by fixing every index but one.
double	get(int... keys) Return a value given a specific i-entry.
java.util.Collection<java.lang.Integer>	getIndex(int d, int key) Return indices (positions) of a key in dimension d.
int	getIndexDimension(int index)
java.util.List<java.lang.Integer>	getIndices(int user, int item) Return all entries for a (user, item) pair
int	getItemDimension()
java.util.List<java.lang.Integer>	getRelevantKeys(int sd, int key, int td) Return keys in a target dimension td related with a key in dimension sd.
java.util.List<java.lang.Integer>	getTargetKeyFromSubKey(java.lang.Integer[] subKey)
int	getUserDimension()
double	innerProduct(SparseTensor st)
boolean	isCubical()
boolean	isDiagonal()
boolean	isDimMatch(SparseTensor st) Return whether two sparse tensors have the same dimensions
boolean	isIndexed(int d) Return whether a dimension d is indexed.
java.util.Iterator<TensorEntry>	iterator()
int	key(int d, int index) Return key in the position index of dimension d.
int[]	keys(int index) Return keys in a given index
static void	main(java.lang.String[] args) Usage demonstration
SparseMatrix	matricization(int n) Re-ordering entries of a tensor into a matrix
double	mean()
SparseTensor	modeProduct(DenseMatrix mat, int dim) n-mode product of a tensor A (I1 x I2 x ...
SparseTensor	modeProduct(DenseVector vec, int dim) n-mode product of a tensor A (I1 x I2 x ...
double	norm()
int	numDimensions()
SparseMatrix	rateMatrix() retrieve a rating matrix from the tensor.
boolean	remove(int... keys) remove an entry with specific keys.
void	set(double val, int... keys) Set a value to a specific i-entry
void	setItemDimension(int itemDimension)
void	setUserDimension(int userDimension)
void	shuffle() Shuffle a sparse tensor
int	size()
SparseMatrix	slice(int rowDim, int colDim, int... otherKeys) Slice is a two-dimensional sub-array of a tensor, defined by fixing all but two indices.
java.lang.String	toString()
double	value(int index) Return value in a given index.

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

numDimensions

public int numDimensions

number of dimensions, i.e., the order (or modes, ways) of a tensor

dimensions

public int[] dimensions

ndKeys

public java.util.List<java.lang.Integer>[] ndKeys

values

public java.util.List<java.lang.Double> values

Constructor Detail

SparseTensor

public SparseTensor(int... dims)

Construct an empty sparse tensor

Parameters:

dims - dimensions of a tensor

SparseTensor

public SparseTensor(int[] dims,
            java.util.List<java.lang.Integer>[] nds,
            java.util.List<java.lang.Double> vals)

Construct a sparse tensor with indices and values

Parameters:

dims - dimensions of a tensor

nds - n-dimensional keys

vals - entry values

Method Detail

clone

public SparseTensor clone()

make a deep clone

Overrides:

clone in class java.lang.Object

add

public void add(double val,
       int... keys)
         throws java.lang.Exception

Add a value to a given i-entry

Parameters:

val - value to add

keys - n-dimensional keys

Throws:

java.lang.Exception - if error occurs during adding

set

public void set(double val,
       int... keys)
         throws java.lang.Exception

Set a value to a specific i-entry

Parameters:

val - value to set

keys - n-dimensional keys

Throws:

java.lang.Exception - if error occurs during setting

remove

public boolean remove(int... keys)
               throws java.lang.Exception

remove an entry with specific keys. NOTE: it is not recommended to remove by entry index because the index may be changed after operations are executed, especially operation as addiction, remove, etc.

Parameters:

keys - n-dimensional keys

Returns:

true if the operation succeed

Throws:

java.lang.Exception - if error occurs during removing

getIndices

public java.util.List<java.lang.Integer> getIndices(int user,
                                           int item)

Return all entries for a (user, item) pair

Parameters:

user - user index

item - item index

Returns:

all entries for a (user, item) pair

getTargetKeyFromSubKey

public java.util.List<java.lang.Integer> getTargetKeyFromSubKey(java.lang.Integer[] subKey)
                                                         throws java.lang.Exception

Parameters:

subKey - a numDimensions-1 dimension subKey

Returns:

all entries for a numDimensions-1 dimension subKey

Throws:

java.lang.Exception - if error occurs during getting

fiber

public SparseVector fiber(int dim,
                 int... keys)

A fiber is defined by fixing every index but one. For example, a matrix column is a mode-1 fiber and a matrix row is a mode-2 fiber.

Parameters:

dim - the dimension where values can vary

keys - the other fixed dimension keys

Returns:

a sparse vector

contains

public boolean contains(int... keys)
                 throws java.lang.Exception

Check if a given keys exists

Parameters:

keys - keys to check

Returns:

true if found, and false otherwise

Throws:

java.lang.Exception - if error occurs during checking

isIndexed

public boolean isIndexed(int d)

Return whether a dimension d is indexed.

Parameters:

d - a dimension d

Returns:

whether a dimension d is indexed

isCubical

public boolean isCubical()

Returns:

whether a tensor is cubical

isDiagonal

public boolean isDiagonal()

Returns:

whether a tensor is diagonal

get

public double get(int... keys)
           throws java.lang.Exception

Return a value given a specific i-entry.

Parameters:

keys - a specific i-entry

Returns:

a value given a specific i-entry

Throws:

java.lang.Exception - if error occurs during getting

shuffle

public void shuffle()

Shuffle a sparse tensor

buildIndex

public void buildIndex(int... dims)

build index at dimensions nd

Parameters:

dims - dimensions to be indexed

buildIndices

public void buildIndices()

build index for all dimensions

getIndex

public java.util.Collection<java.lang.Integer> getIndex(int d,
                                               int key)

Return indices (positions) of a key in dimension d.

Parameters:

d - dimension

key - key value

Returns:

indices (positions) of a key in dimension d

keys

public int[] keys(int index)

Return keys in a given index

Parameters:

index - a given index

Returns:

keys in a given index

key

public int key(int d,
      int index)

Return key in the position index of dimension d.

Parameters:

d - dimension

index - a given index

Returns:

key in the position index of dimension d

value

public double value(int index)

Return value in a given index.

Parameters:

index - a given index

Returns:

value in a given index

getRelevantKeys

public java.util.List<java.lang.Integer> getRelevantKeys(int sd,
                                                int key,
                                                int td)

Return keys in a target dimension td related with a key in dimension sd.

Parameters:

sd - source dimension

key - key in the source dimension

td - target dimension

Returns:

keys in a target dimension td related with a key in dimension sd

size

public int size()

Specified by:

size in interface DataSet

Returns:

number of entries of the tensor

slice

public SparseMatrix slice(int rowDim,
                 int colDim,
                 int... otherKeys)

Slice is a two-dimensional sub-array of a tensor, defined by fixing all but two indices.

Parameters:

rowDim - row dimension

colDim - column dimension

otherKeys - keys of other dimensions

Returns:

a sparse matrix

matricization

public SparseMatrix matricization(int n)

Re-ordering entries of a tensor into a matrix

Parameters:

n - mode or dimension

Returns:

an unfolded or flatten matrix

modeProduct

public SparseTensor modeProduct(DenseMatrix mat,
                       int dim)
                         throws java.lang.Exception

n-mode product of a tensor A (I1 x I2 x ... x IN) with a matrix B (J x In), denoted by A Xn B

Parameters:

mat - mat to be multiplied

dim - mode/dimension of the tensor to be used

Returns:

a new tensor in (I1 x I2 x ... x In-1 x J x In+1 x ... x IN)

Throws:

java.lang.Exception - if error occurs during product

modeProduct

public SparseTensor modeProduct(DenseVector vec,
                       int dim)
                         throws java.lang.Exception

n-mode product of a tensor A (I1 x I2 x ... x IN) with a vector B (1 x In), denoted by A Xn B

Parameters:

vec - vector to be multiplied

dim - mode/dimension of the tensor to be used

Returns:

a new tensor in (I1 x I2 x ... x In-1 x 1 x In+1 x ... x IN)

Throws:

java.lang.Exception - if error occurs during product

rateMatrix

public SparseMatrix rateMatrix()

retrieve a rating matrix from the tensor. Warning: it assumes there is at most one entry for each (user, item) pair.

Returns:

a sparse rating matrix

iterator

public java.util.Iterator<TensorEntry> iterator()

Specified by:

iterator in interface java.lang.Iterable<TensorEntry>

norm

public double norm()

Returns:

norm of a tensor

mean

public double mean()

Returns:

mean of a tensor

innerProduct

public double innerProduct(SparseTensor st)
                    throws java.lang.Exception

Parameters:

st - another tensor

Returns:

inner product with another tensor

Throws:

java.lang.Exception - if error occurs during product

isDimMatch

public boolean isDimMatch(SparseTensor st)

Return whether two sparse tensors have the same dimensions

Parameters:

st - a given SparseTensor

Returns:

whether two sparse tensors have the same dimensions

getUserDimension

public int getUserDimension()

getIndexDimension

public int getIndexDimension(int index)

setUserDimension

public void setUserDimension(int userDimension)

getItemDimension

public int getItemDimension()

setItemDimension

public void setItemDimension(int itemDimension)

dimensions

public int[] dimensions()

numDimensions

public int numDimensions()

Returns:

the number of a tensor's dimensions, a.k.a., the order of a tensor

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

main

public static void main(java.lang.String[] args)
                 throws java.lang.Exception

Usage demonstration

Parameters:

args - arguments

Throws:

java.lang.Exception - if error occurs