Module flag4j

Package org.flag4j.arrays.backend.semiring_arrays

Class AbstractCooSemiringVector<T extends AbstractCooSemiringVector<T,U,V,W,Y>,U extends AbstractDenseSemiringVector<U,W,Y>,V extends AbstractCooSemiringMatrix<V,W,T,Y>,W extends AbstractDenseSemiringMatrix<W,U,Y>,Y extends Semiring<Y>>

java.lang.Object

org.flag4j.arrays.backend.AbstractTensor<T,Semiring<Y>[],Y>

org.flag4j.arrays.backend.semiring.AbstractCooSemiringVector<T,U,V,W,Y>

Type Parameters:

T - Type of this vector.

U - Type of equivalent dense vector.

V - Type of matrix equivalent to T.

Y - Type of dense matrix equivalent to U.

Y - Type of the semiring element in this vector.

All Implemented Interfaces:

Serializable, SemiringTensorMixin<T,U,Y>, TensorOverSemiRing<T,U,Semiring<Y>[],Y>, VectorMixin<T,V,W,Y>, TensorBinaryOpsMixin<T,T>, TensorMixin<T,Semiring<Y>[],Y>

public abstract class AbstractCooSemiringVector<T extends AbstractCooSemiringVector<T,U,V,W,Y>,U extends AbstractDenseSemiringVector<U,W,Y>,V extends AbstractCooSemiringMatrix<V,W,T,Y>,W extends AbstractDenseSemiringMatrix<W,U,Y>,Y extends Semiring<Y>>
extends AbstractTensor<T,Semiring<Y>[],Y>
implements SemiringTensorMixin<T,U,Y>, VectorMixin<T,V,W,Y>

A sparse vector stored in coordinate list (COO) format. The AbstractTensor.entries of this COO vector are elements of a Semiring.

The non-zero entries and non-zero indices of a COO vector are mutable but the AbstractTensor.shape and total number of non-zero entries is fixed.

Sparse vectors allow for the efficient storage of and operations on large vectors that contain many zero values.

COO vectors are optimized for large hyper-sparse vectors (i.e. vectors which contain almost all zeros relative to the size of the vector).

A sparse COO vector is stored as:

• The full AbstractTensor.shape/VectorMixin.size() of the vector.
• The non-zero AbstractTensor.entries of the vector. All other entries in the vector are assumed to be zero. Zero values can also explicitly be stored in AbstractTensor.entries.
• The indices of the non-zero values in the sparse vector.

Note: many operations assume that the entries of the COO vector are sorted lexicographically. However, this is not explicitly verified. Every operation implemented in this class will preserve the lexicographical sorting.

If indices need to be sorted for any reason, call sortIndices().

See Also:

• Serialized Form

Field Summary

Fields

Modifier and Type	Field	Description
final int[]	indices	Indices of the non-zero values of this sparse COO vector.
final int	nnz	The number of non-zero entries in this sparse COO vector.
final int	size	The total size of this sparse COO vector (including zero values).
final double	sparsity	The sparsity of this matrix.
private Semiring<Y>	zeroElement	The zero element for the semiring that this tensor's elements belong to.

Fields inherited from class org.flag4j.arrays.backend.AbstractTensor

entries, rank, shape

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	AbstractCooSemiringVector(int size, Semiring<Y>[] entries, int[] indices)	Creates a tensor with the specified entries and shape.

Method Summary

Modifier and Type	Method	Description
T	add(T b)	Computes the element-wise sum between two tensors of the same shape.
T	copy()	Creates a deep copy of this tensor.
Y	dot(T b)	Computes the dot product between two vectors.
T	elemMult(T b)	Computes the element-wise multiplication of two tensors of the same shape.
T	flatten()	Flattens tensor to single dimension while preserving order of entries.
T	flatten(int axis)	Flattens a tensor along the specified axis.
Y	get(int... target)	Gets the element of this tensor at the specified indices.
Y	getZeroElement()	Gets the zero element for the field of this vector.
Y	inner(T b)	Computes the inner product between two vectors.
T	join(T b)	Joints specified vector with this vector.
int	length()	Gets the length of a vector.
abstract W	makeLikeDenseMatrix(Shape shape, Semiring<Y>... entries)	Constructs a dense matrix of a similar type as this vector with the specified shape and entries.
abstract U	makeLikeDenseTensor(Shape shape, Semiring<Y>... entries)	Constructs a dense vector of a similar type as this vector with the specified shape and entries.
abstract V	makeLikeMatrix(Shape shape, Semiring<Y>[] entries, int[] rowIndices, int[] colIndices)	Constructs a COO matrix with the specified shape, non-zero entries, and row and column indices.
abstract T	makeLikeTensor(Shape shape, List<Semiring<Y>> entries, List<Integer> indices)	Constructs a COO vector with the specified shape, non-zero entries, and non-zero indices.
abstract T	makeLikeTensor(Shape shape, Semiring<Y>[] entries, int[] indices)	Constructs a sparse COO vector of the same type as this vector with the specified non-zero entries and indices.
W	outer(T b)	Computes the outer product of two vectors.
V	repeat(int n, int axis)	Repeats a vector n times along a certain axis to create a matrix.
T	reshape(Shape newShape)	Copies and reshapes this tensor.
T	set(Y value, int... target)	Sets the element of this tensor at the specified indices.
void	setZeroElement(Semiring<Y> zeroElement)	Sets the zero element for the field of this tensor.
void	sortIndices()	Sorts the indices of this tensor in lexicographical order while maintaining the associated value for each index.
V	stack(T b, int axis)	Stacks two vectors along specified axis.
T	T(int... axes)	Computes the transpose of this tensor.
T	T(int axis1, int axis2)	Computes the transpose of a tensor by exchanging axis1 and axis2.
U	tensorDot(T src2, int[] aAxes, int[] bAxes)	Computes the tensor contraction of this tensor with a specified tensor over the specified set of axes.
T	tensorTr(int axis1, int axis2)	Computes the generalized trace of this tensor along the specified axes.
V	toMatrix(boolean columVector)	Converts a vector to an equivalent matrix representing either a row or column vector.

Methods inherited from class org.flag4j.arrays.backend.AbstractTensor

getEntries, getRank, getShape, makeLikeTensor, reshape, sameShape, totalEntries

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.flag4j.arrays.backend.semiring.SemiringTensorMixin

add, addEq, argmax, argmin, isOnes, isZeros, max, min, mult, multEq, prod, sum

Methods inherited from interface org.flag4j.arrays.backend.TensorMixin

T

Methods inherited from interface org.flag4j.arrays.backend.semiring.TensorOverSemiRing

getEntries, getRank, getShape, makeLikeTensor, tensorDot, tensorDot, tensorDot, tensorTr

Methods inherited from interface org.flag4j.arrays.backend.VectorMixin

size, stack, toMatrix

Field Details

zeroElement

private Semiring<Y extends Semiring<Y>> zeroElement

The zero element for the semiring that this tensor's elements belong to.

indices

public final int[] indices

Indices of the non-zero values of this sparse COO vector.

nnz

public final int nnz

The number of non-zero entries in this sparse COO vector.

size

public final int size

The total size of this sparse COO vector (including zero values).

sparsity

public final double sparsity

The sparsity of this matrix.

Constructor Details

AbstractCooSemiringVector

protected AbstractCooSemiringVector(int size,
 Semiring<Y>[] entries,
 int[] indices)

Creates a tensor with the specified entries and shape.

Parameters:

entries - Entries of this tensor. If this tensor is dense, this specifies all entries within the tensor. If this tensor is sparse, this specifies only the non-zero entries of the tensor.

shape - Shape of this tensor.

Method Details

makeLikeTensor

public abstract T makeLikeTensor(Shape shape,
 Semiring<Y>[] entries,
 int[] indices)

Constructs a sparse COO vector of the same type as this vector with the specified non-zero entries and indices.

Parameters:

shape - Shape of the vector to construct.

entries - Non-zero entries of the vector to construct.

indices - Non-zero row indices of the vector to construct.

Returns:

A sparse COO vector of the same type as this vector with the specified non-zero entries and indices.

makeLikeDenseTensor

public abstract U makeLikeDenseTensor(Shape shape,
 Semiring<Y>... entries)

Constructs a dense vector of a similar type as this vector with the specified shape and entries.

Parameters:

shape - Shape of the vector to construct.

entries - Entries of the vector to construct.

Returns:

A dense vector of a similar type as this vector with the specified entries.

makeLikeDenseMatrix

public abstract W makeLikeDenseMatrix(Shape shape,
 Semiring<Y>... entries)

Constructs a dense matrix of a similar type as this vector with the specified shape and entries.

Parameters:

shape - Shape of the matrix to construct.

entries - Entries of the matrix to construct.

Returns:

A dense matrix of a similar type as this vector with the specified entries.

makeLikeTensor

public abstract T makeLikeTensor(Shape shape,
 List<Semiring<Y>> entries,
 List<Integer> indices)

Constructs a COO vector with the specified shape, non-zero entries, and non-zero indices.

Parameters:

shape - Shape of the vector.

entries - Non-zero values of the vector.

indices - Indices of the non-zero values in the vector.

Returns:

A COO vector of the same type as this vector with the specified shape, non-zero entries, and non-zero indices.

makeLikeMatrix

public abstract V makeLikeMatrix(Shape shape,
 Semiring<Y>[] entries,
 int[] rowIndices,
 int[] colIndices)

Constructs a COO matrix with the specified shape, non-zero entries, and row and column indices.

Parameters:

shape - Shape of the matrix to construct.

entries - Non-zero entries of the matrix.

rowIndices - Row indices of the matrix.

colIndices - Column indices of the matrix.

Returns:

A COO matrix of similar type as this vector with the specified shape, non-zero entries, and non-zero row/col indices.

sortIndices

public void sortIndices()

Sorts the indices of this tensor in lexicographical order while maintaining the associated value for each index.

get

public Y get(int... target)

Gets the element of this tensor at the specified indices.

Specified by:

get in interface TensorMixin<T extends AbstractCooSemiringVector<T,U,V,W,Y>,U extends AbstractDenseSemiringVector<U,W,Y>,V extends AbstractCooSemiringMatrix<V,W,T,Y>>

Specified by:

get in class AbstractTensor<T extends AbstractCooSemiringVector<T,U,V,W,Y>,Semiring<Y extends Semiring<Y>>[],Y extends Semiring<Y>>

Parameters:

target - Indices of the element to get.

Returns:

The element of this tensor at the specified indices.

Throws:

IndexOutOfBoundsException - If any {target} are not within this tensor.

T

public T T(int axis1,
 int axis2)

Computes the transpose of a tensor by exchanging axis1 and axis2.

Specified by:

T in interface TensorMixin<T extends AbstractCooSemiringVector<T,U,V,W,Y>,U extends AbstractDenseSemiringVector<U,W,Y>,V extends AbstractCooSemiringMatrix<V,W,T,Y>>

Parameters:

axis1 - First axis to exchange.

axis2 - Second axis to exchange.

Returns:

The transpose of this tensor according to the specified axes.

Throws:

IndexOutOfBoundsException - If either axis1 or axis2 are out of bounds for the rank of this tensor.

See Also:

• TensorMixin.T()
• T(int...)

T

public T T(int... axes)

Computes the transpose of this tensor. That is, permutes the axes of this tensor so that it matches the permutation specified by axes.

Specified by:

T in interface TensorMixin<T extends AbstractCooSemiringVector<T,U,V,W,Y>,U extends AbstractDenseSemiringVector<U,W,Y>,V extends AbstractCooSemiringMatrix<V,W,T,Y>>

Parameters:

axes - Permutation of tensor axis. If the tensor has rank N, then this must be an array of length N which is a permutation of {0, 1, 2, ..., N-1}.

Returns:

The transpose of this tensor with its axes permuted by the axes array.

Throws:

IllegalArgumentException - If axes is not a permutation of {1, 2, 3, ... N-1}.

See Also:

• T(int, int)
• TensorMixin.T()

copy

public T copy()

Creates a deep copy of this tensor.

Specified by:

copy in interface TensorMixin<T extends AbstractCooSemiringVector<T,U,V,W,Y>,U extends AbstractDenseSemiringVector<U,W,Y>,V extends AbstractCooSemiringMatrix<V,W,T,Y>>

Returns:

A deep copy of this tensor.

set

public T set(Y value,
 int... target)

Sets the element of this tensor at the specified indices.

Specified by:

set in class AbstractTensor<T extends AbstractCooSemiringVector<T,U,V,W,Y>,Semiring<Y extends Semiring<Y>>[],Y extends Semiring<Y>>

Parameters:

value - New value to set the specified index of this tensor to.

target - Indices of the element to set.

Returns:

If this tensor is dense, a reference to this tensor is returned. If this tensor is sparse, a copy of this tensor with the updated value is returned.

Throws:

IndexOutOfBoundsException - If indices is not within the bounds of this tensor.

flatten

public T flatten()

Flattens tensor to single dimension while preserving order of entries.

Specified by:

flatten in class AbstractTensor<T extends AbstractCooSemiringVector<T,U,V,W,Y>,Semiring<Y extends Semiring<Y>>[],Y extends Semiring<Y>>

Returns:

The flattened tensor.

See Also:

• flatten(int)

flatten

public T flatten(int axis)

Flattens a tensor along the specified axis. Unlike flatten()

Specified by:

flatten in class AbstractTensor<T extends AbstractCooSemiringVector<T,U,V,W,Y>,Semiring<Y extends Semiring<Y>>[],Y extends Semiring<Y>>

Parameters:

axis - Axis along which to flatten tensor.

Throws:

ArrayIndexOutOfBoundsException - If the axis is not positive or larger than this.AbstractTensor.getRank()-1.

See Also:

• flatten()

reshape

public T reshape(Shape newShape)

Copies and reshapes this tensor.

Specified by:

reshape in class AbstractTensor<T extends AbstractCooSemiringVector<T,U,V,W,Y>,Semiring<Y extends Semiring<Y>>[],Y extends Semiring<Y>>

Parameters:

newShape - New shape for the tensor.

Returns:

A copy of this tensor with the new shape.

Throws:

TensorShapeException - If newShape is not broadcastable to this.shape.

join

public T join(T b)

Joints specified vector with this vector. That is, creates a vector of length this.length() + b.length() containing first the elements of this vector followed by the elements of b.

Specified by:

join in interface VectorMixin<T extends AbstractCooSemiringVector<T,U,V,W,Y>,U extends AbstractDenseSemiringVector<U,W,Y>,V extends AbstractCooSemiringMatrix<V,W,T,Y>,W extends AbstractDenseSemiringMatrix<W,U,Y>>

Parameters:

b - Vector to join with this vector.

Returns:

A vector resulting from joining the specified vector with this vector.

inner

public Y inner(T b)

Computes the inner product between two vectors.

Note: this method is distinct from dot(AbstractCooSemiringVector). The inner product is equivalent to the dot product of this tensor with the conjugation of b.

Specified by:

inner in interface VectorMixin<T extends AbstractCooSemiringVector<T,U,V,W,Y>,U extends AbstractDenseSemiringVector<U,W,Y>,V extends AbstractCooSemiringMatrix<V,W,T,Y>,W extends AbstractDenseSemiringMatrix<W,U,Y>>

Parameters:

b - Second vector in the inner product.

Returns:

The inner product between this vector and the vector b.

Throws:

IllegalArgumentException - If this vector and vector b do not have the same number of entries.

See Also:

• dot(AbstractCooSemiringVector)

dot

public Y dot(T b)

Computes the dot product between two vectors.

Note: this method is distinct from inner(AbstractCooSemiringVector). The inner product is equivalent to the dot product of this tensor with the conjugation of b.

Specified by:

dot in interface VectorMixin<T extends AbstractCooSemiringVector<T,U,V,W,Y>,U extends AbstractDenseSemiringVector<U,W,Y>,V extends AbstractCooSemiringMatrix<V,W,T,Y>,W extends AbstractDenseSemiringMatrix<W,U,Y>>

Parameters:

b - Second vector in the dot product.

Returns:

The dot product between this vector and the vector b.

Throws:

IllegalArgumentException - If this vector and vector b do not have the same number of entries.

See Also:

• inner(AbstractCooSemiringVector)

length

public int length()

Gets the length of a vector. Same as VectorMixin.size().

WARNING: This method will throw a ArithmeticException if the total number of entries in this vector is greater than the maximum integer. In this case, the true size of this vector can still be found by calling shape.totalEntries() on this vector.

Specified by:

length in interface VectorMixin<T extends AbstractCooSemiringVector<T,U,V,W,Y>,U extends AbstractDenseSemiringVector<U,W,Y>,V extends AbstractCooSemiringMatrix<V,W,T,Y>,W extends AbstractDenseSemiringMatrix<W,U,Y>>

Returns:

The length, i.e. the number of entries, in this vector.

Throws:

ArithmeticException - If the total number of entries in this vector is greater than the maximum integer.

repeat

public V repeat(int n,
 int axis)

Repeats a vector n times along a certain axis to create a matrix.

Specified by:

repeat in interface VectorMixin<T extends AbstractCooSemiringVector<T,U,V,W,Y>,U extends AbstractDenseSemiringVector<U,W,Y>,V extends AbstractCooSemiringMatrix<V,W,T,Y>,W extends AbstractDenseSemiringMatrix<W,U,Y>>

Parameters:

n - Number of times to repeat vector.

axis - Axis along which to repeat vector:

• If axis=0, then the vector will be treated as a row vector and stacked vertically n times.
• If axis=1 then the vector will be treated as a column vector and stacked horizontally n times.

Returns:

A matrix whose rows/columns are this vector repeated.

stack

public V stack(T b,
 int axis)

Stacks two vectors along specified axis.

Stacking two vectors of length n along axis 0 stacks the vectors as if they were row vectors resulting in a 2-by-n matrix.

Stacking two vectors of length n along axis 1 stacks the vectors as if they were column vectors resulting in a n-by-2 matrix.

Specified by:

stack in interface VectorMixin<T extends AbstractCooSemiringVector<T,U,V,W,Y>,U extends AbstractDenseSemiringVector<U,W,Y>,V extends AbstractCooSemiringMatrix<V,W,T,Y>,W extends AbstractDenseSemiringMatrix<W,U,Y>>

Parameters:

b - Vector to stack with this vector.

axis - Axis along which to stack vectors. If axis=0, then vectors are stacked as if they are row vectors. If axis=1, then vectors are stacked as if they are column vectors.

Returns:

The result of stacking this vector and the vector b.

Throws:

IllegalArgumentException - If the number of entries in this vector is different from the number of entries in the vector b.

IllegalArgumentException - If axis is not either 0 or 1.

outer

public W outer(T b)

Computes the outer product of two vectors.

Specified by:

outer in interface VectorMixin<T extends AbstractCooSemiringVector<T,U,V,W,Y>,U extends AbstractDenseSemiringVector<U,W,Y>,V extends AbstractCooSemiringMatrix<V,W,T,Y>,W extends AbstractDenseSemiringMatrix<W,U,Y>>

Parameters:

b - Second vector in the outer product.

Returns:

The result of the vector outer product between this vector and b.

Throws:

IllegalArgumentException - If the two vectors do not have the same number of entries.

toMatrix

public V toMatrix(boolean columVector)

Converts a vector to an equivalent matrix representing either a row or column vector.

Specified by:

toMatrix in interface VectorMixin<T extends AbstractCooSemiringVector<T,U,V,W,Y>,U extends AbstractDenseSemiringVector<U,W,Y>,V extends AbstractCooSemiringMatrix<V,W,T,Y>,W extends AbstractDenseSemiringMatrix<W,U,Y>>

Parameters:

columVector - Flag indicating whether to convert this vector to a matrix representing a row or column vector:

If true, the vector will be converted to a matrix representing a column vector.

If false, The vector will be converted to a matrix representing a row vector.

Returns:

A matrix equivalent to this vector.

add

public T add(T b)

Computes the element-wise sum between two tensors of the same shape.

Specified by:

add in interface TensorOverSemiRing<T extends AbstractCooSemiringVector<T,U,V,W,Y>,U extends AbstractDenseSemiringVector<U,W,Y>,V extends AbstractCooSemiringMatrix<V,W,T,Y>,W extends AbstractDenseSemiringMatrix<W,U,Y>>

Parameters:

b - Second tensor in the element-wise sum.

Returns:

The sum of this tensor with b.

Throws:

TensorShapeException - If this tensor and b do not have the same shape.

elemMult

public T elemMult(T b)

Computes the element-wise multiplication of two tensors of the same shape.

Specified by:

elemMult in interface TensorOverSemiRing<T extends AbstractCooSemiringVector<T,U,V,W,Y>,U extends AbstractDenseSemiringVector<U,W,Y>,V extends AbstractCooSemiringMatrix<V,W,T,Y>,W extends AbstractDenseSemiringMatrix<W,U,Y>>

Parameters:

b - Second tensor in the element-wise product.

Returns:

The element-wise product between this tensor and b.

Throws:

IllegalArgumentException - If this tensor and b do not have the same shape.

tensorDot

public U tensorDot(T src2,
 int[] aAxes,
 int[] bAxes)

Computes the tensor contraction of this tensor with a specified tensor over the specified set of axes. That is, computes the sum of products between the two tensors along the specified set of axes.

Specified by:

tensorDot in interface TensorOverSemiRing<T extends AbstractCooSemiringVector<T,U,V,W,Y>,U extends AbstractDenseSemiringVector<U,W,Y>,V extends AbstractCooSemiringMatrix<V,W,T,Y>,W extends AbstractDenseSemiringMatrix<W,U,Y>>

Parameters:

src2 - Tensor to contract with this tensor.

aAxes - Axes along which to compute products for this tensor.

bAxes - Axes along which to compute products for src2 tensor.

Returns:

The tensor dot product over the specified axes.

Throws:

IllegalArgumentException - If the two tensors shapes do not match along the specified axes pairwise in aAxes and bAxes.

IllegalArgumentException - If aAxes and bAxes do not match in length, or if any of the axes are out of bounds for the corresponding tensor.

tensorTr

public T tensorTr(int axis1,
 int axis2)

Computes the generalized trace of this tensor along the specified axes.

The generalized tensor trace is the sum along the diagonal values of the 2D sub-arrays of this tensor specified by axis1 and axis2. The shape of the resulting tensor is equal to this tensor with the axis1 and axis2 removed.

Specified by:

tensorTr in interface TensorOverSemiRing<T extends AbstractCooSemiringVector<T,U,V,W,Y>,U extends AbstractDenseSemiringVector<U,W,Y>,V extends AbstractCooSemiringMatrix<V,W,T,Y>,W extends AbstractDenseSemiringMatrix<W,U,Y>>

Parameters:

axis1 - First axis for 2D sub-array.

axis2 - Second axis for 2D sub-array.

Returns:

The generalized trace of this tensor along axis1 and axis2.

Throws:

IndexOutOfBoundsException - If the two axes are not both larger than zero and less than this tensors rank.

IllegalArgumentException - If axis1 == @code axis2 or this.shape.get(axis1) != this.shape.get(axis1) (i.e. the axes are equal or the tensor does not have the same length along the two axes.)

getZeroElement

public Y getZeroElement()

Gets the zero element for the field of this vector.

Returns:

The zero element for the field of this vector. If it could not be determined during construction of this object and has not been set explicitly by setZeroElement(Semiring) then null will be returned.

setZeroElement

public void setZeroElement(Semiring<Y> zeroElement)

Sets the zero element for the field of this tensor.

Parameters:

zeroElement - The zero element of this tensor.

Throws:

IllegalArgumentException - If zeroElement is not an additive identity for the semiring.