Class AbstractCooSemiringTensor<T extends AbstractCooSemiringTensor<T,U,V>,U extends AbstractDenseSemiringTensor<U,V>,V extends Semiring<V>>

java.lang.Object
org.flag4j.arrays.backend.AbstractTensor<T,V[],V>
org.flag4j.arrays.backend.semiring_arrays.AbstractCooSemiringTensor<T,U,V>
Type Parameters:
T - Type of this sparse COO tensor.
U - Type of dense tensor equivalent to T. This type parameter is required because some ops (e.g. tensorDot(AbstractCooSemiringTensor, int[], int[]) ) between two sparse tensors results in a dense tensor.
V - Type of the Semiring which the data of this tensor belong to.
All Implemented Interfaces:
Serializable, SemiringTensorMixin<T,T,V>, TensorOverSemiring<T,T,V[],V>
Direct Known Subclasses:
AbstractCooRingTensor, CooSemiringTensor
public abstract class AbstractCooSemiringTensor<T extends AbstractCooSemiringTensor<T,U,V>,U extends AbstractDenseSemiringTensor<U,V>,V extends Semiring<V>> extends AbstractTensor<T,V[],V> implements SemiringTensorMixin<T,T,V>

Base class for all sparse tensors stored in coordinate list (COO) format. The data of this COO tensor are elements of a Semiring

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

Sparse tensors allow for the efficient storage of and ops on tensors that contain many zero values.

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

A sparse COO tensor is stored as:

  • The full shape of the tensor.
  • The non-zero AbstractTensor.data of the tensor. All other data in the tensor are assumed to be zero. Zero value can also explicitly be stored in AbstractTensor.data.

  • The indices of the non-zero value in the sparse tensor. Many ops assume indices to be sorted in a row-major format (i.e. last index increased fastest) but often this is not explicitly verified.

    The indices array has shape (nnz, rank) where nnz is the number of non-zero data in this sparse tensor and rank is the tensor rank of the tensor. This means indices[i] is the ND index of data[i].

See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    final int[][]
    indices
    The non-zero indices of this sparse tensor.
    final int
    nnz
    The number of non-zero data in this sparse tensor.
    final double
    sparsity
    Stores the sparsity of this matrix.
    protected V
    zeroElement
    The zero element for the semiring that this tensor's elements belong to.

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

    data, rank, shape

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    AbstractCooSemiringTensor(Shape shape, V[] data, int[][] indices)
    Creates a tensor with the specified data 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.
    int[]
    argmax()
    Finds the indices of the maximum (non-zero) value in this tensor.
    int[]
    argmin()
    Finds the indices of the minimum (non-zero) value in this tensor.
    T
    coalesce()
    Coalesces this sparse COO tensor.
    T
    coalesce(BinaryOperator<V> aggregator)
    Coalesces this sparse COO tensor.
    T
    copy()
    Creates a deep copy of this tensor.
    double
    density()
    Gets the density of this tensor as a decimal percentage.
    T
    dropZeros()
    Drops any explicit zeros in this sparse COO tensor.
    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 data.
    T
    flatten(int axis)
    Flattens a tensor along the specified axis.
    V
    get(int... target)
    Gets the element of this tensor at the specified target.
    V
    getZeroElement()
    Gets the zero element for the field of this tensor.
    abstract U
    makeLikeDenseTensor(Shape shape, V[] entries)
    Constructs a dense tensor that is a similar type as this sparse COO tensor.
    abstract T
    makeLikeTensor(Shape shape, List<V> data, List<int[]> indices)
    Constructs a tensor of the same type as this tensor with the specified shape and non-zero data.
    abstract T
    makeLikeTensor(Shape shape, V[] data, int[][] indices)
    Constructs a tensor of the same type as this tensor with the specified shape and non-zero data.
    V
    max()
    Finds the maximum (non-zero) value in this tensor.
    V
    min()
    Finds the minimum (non-zero) value in this tensor.
    T
    reshape(Shape newShape)
    Copies and reshapes this tensor.
    T
    set(V value, int... target)
    Sets the element of this tensor at the specified target.
    void
    setZeroElement(V 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.
    double
    sparsity()
    Gets the sparsity of this tensor as a decimal percentage.
    T
    T()
    Computes the transpose of a tensor by exchanging the first and last axes of this tensor.
    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.
    U
    toDense()
    Converts this COO tensor to an equivalent dense tensor.

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

    getData, 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_arrays.SemiringTensorMixin

    add, addEq, isOnes, isZeros, makeEmptyDataArray, mult, multEq, prod, sum

    Methods inherited from interface org.flag4j.arrays.backend.semiring_arrays.TensorOverSemiring

    getData, getRank, getShape, makeLikeTensor, tensorDot, tensorDot, tensorDot, tensorTr

  • Field Details

    • zeroElement

      protected V extends Semiring<V> zeroElement
      The zero element for the semiring that this tensor's elements belong to.

    • indices

      public final int[][] indices

      The non-zero indices of this sparse tensor.

      Has shape (nnz, rank) where nnz is the number of non-zero data in this sparse tensor.

    • nnz

      public final int nnz
      The number of non-zero data in this sparse tensor.

    • sparsity

      public final double sparsity
      Stores the sparsity of this matrix.

  • Constructor Details

    • AbstractCooSemiringTensor

      protected AbstractCooSemiringTensor(Shape shape, V[] data, int[][] indices)
      Creates a tensor with the specified data and shape.
      Parameters:
      shape - Shape of this tensor.
      data - Non-zero data of this tensor of this tensor. If this tensor is dense, this specifies all data within the tensor. If this tensor is sparse, this specifies only the non-zero data of the tensor.

  • Method Details

    • makeLikeTensor

      public abstract T makeLikeTensor(Shape shape, V[] data, int[][] indices)
      Constructs a tensor of the same type as this tensor with the specified shape and non-zero data.
      Parameters:
      shape - Shape of the tensor to construct.
      data - Non-zero data of the tensor to construct.
      indices - Indices of the non-zero data of the tensor.
      Returns:
      A tensor of the same type as this tensor with the specified shape and non-zero data.

    • makeLikeTensor

      public abstract T makeLikeTensor(Shape shape, List<V> data, List<int[]> indices)
      Constructs a tensor of the same type as this tensor with the specified shape and non-zero data.
      Parameters:
      shape - Shape of the tensor to construct.
      data - Non-zero data of the tensor to construct.
      indices - Indices of the non-zero data of the tensor.
      Returns:
      A tensor of the same type as this tensor with the specified shape and non-zero data.

    • makeLikeDenseTensor

      public abstract U makeLikeDenseTensor(Shape shape, V[] entries)
      Constructs a dense tensor that is a similar type as this sparse COO tensor.
      Parameters:
      shape - Shape of the tensor to construct.
      entries - The data of the dense tensor to construct.
      Returns:
      A dense tensor that is a similar type as this sparse COO tensor.

    • getZeroElement

      public V getZeroElement()
      Gets the zero element for the field of this tensor.
      Returns:
      The zero element for the field of this tensor. 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(V 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.

    • sparsity

      public double sparsity()
      Gets the sparsity of this tensor as a decimal percentage. That is, the percentage of data in this tensor that are zero.
      Returns:
      The sparsity of this tensor as a decimal percentage.
      See Also:

    • density

      public double density()
      Gets the density of this tensor as a decimal percentage. That is, the percentage of data in this tensor that are non-zero.
      Returns:
      The density of this tensor as a decimal percentage.
      See Also:

    • 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 AbstractCooSemiringTensor<T,U,V>,T extends AbstractCooSemiringTensor<T,U,V>,V extends Semiring<V>[],V extends Semiring<V>>
      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 AbstractCooSemiringTensor<T,U,V>,T extends AbstractCooSemiringTensor<T,U,V>,V extends Semiring<V>[],V extends Semiring<V>>
      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 AbstractCooSemiringTensor<T,U,V>,T extends AbstractCooSemiringTensor<T,U,V>,V extends Semiring<V>[],V extends Semiring<V>>
      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 AbstractCooSemiringTensor<T,U,V>,T extends AbstractCooSemiringTensor<T,U,V>,V extends Semiring<V>[],V extends Semiring<V>>
      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 == 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.)

    • T

      public T T()
      Computes the transpose of a tensor by exchanging the first and last axes of this tensor.
      Overrides:
      T in class AbstractTensor<T extends AbstractCooSemiringTensor<T,U,V>,V extends Semiring<V>[],V extends Semiring<V>>
      Returns:
      The transpose of this tensor.
      See Also:

    • T

      public T T(int axis1, int axis2)
      Computes the transpose of a tensor by exchanging axis1 and axis2.
      Specified by:
      T in class AbstractTensor<T extends AbstractCooSemiringTensor<T,U,V>,V extends Semiring<V>[],V extends Semiring<V>>
      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:

    • 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 class AbstractTensor<T extends AbstractCooSemiringTensor<T,U,V>,V extends Semiring<V>[],V extends Semiring<V>>
      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:
      IndexOutOfBoundsException - If any element of axes is out of bounds for the rank of this tensor.
      IllegalArgumentException - If axes is not a permutation of {1, 2, 3, ... N-1}.
      See Also:

    • copy

      public T copy()
      Creates a deep copy of this tensor.
      Specified by:
      copy in class AbstractTensor<T extends AbstractCooSemiringTensor<T,U,V>,V extends Semiring<V>[],V extends Semiring<V>>
      Returns:
      A deep copy of this tensor.

    • min

      public V min()
      Finds the minimum (non-zero) value in this tensor. If this tensor is complex, then this method finds the smallest value in magnitude.
      Specified by:
      min in interface SemiringTensorMixin<T extends AbstractCooSemiringTensor<T,U,V>,U extends AbstractDenseSemiringTensor<U,V>,V extends Semiring<V>>
      Returns:
      The minimum (non-zero) value in this tensor.

    • max

      public V max()
      Finds the maximum (non-zero) value in this tensor.
      Specified by:
      max in interface SemiringTensorMixin<T extends AbstractCooSemiringTensor<T,U,V>,U extends AbstractDenseSemiringTensor<U,V>,V extends Semiring<V>>
      Returns:
      The maximum (non-zero) value in this tensor.

    • argmin

      public int[] argmin()
      Finds the indices of the minimum (non-zero) value in this tensor.
      Specified by:
      argmin in interface SemiringTensorMixin<T extends AbstractCooSemiringTensor<T,U,V>,U extends AbstractDenseSemiringTensor<U,V>,V extends Semiring<V>>
      Returns:
      The indices of the minimum (non-zero) value in this tensor.

    • argmax

      public int[] argmax()
      Finds the indices of the maximum (non-zero) value in this tensor.
      Specified by:
      argmax in interface SemiringTensorMixin<T extends AbstractCooSemiringTensor<T,U,V>,U extends AbstractDenseSemiringTensor<U,V>,V extends Semiring<V>>
      Returns:
      The indices of the maximum (non-zero) value in this tensor.

    • get

      public V get(int... target)
      Gets the element of this tensor at the specified target.
      Specified by:
      get in class AbstractTensor<T extends AbstractCooSemiringTensor<T,U,V>,V extends Semiring<V>[],V extends Semiring<V>>
      Parameters:
      target - Index of the element to get.
      Returns:
      The element of this tensor at the specified index. If there is a non-zero value with the specified index, that value will be returned. If there is no non-zero value at the specified index than the zero element will attempt to be returned (i.e. the additive identity of the semiring). However, if the zero element could not be determined during construction or if it was not set with setZeroElement(Semiring) then null will be returned.
      Throws:
      ArrayIndexOutOfBoundsException - If any target are not within this tensor.

    • set

      public T set(V value, int... target)
      Sets the element of this tensor at the specified target.
      Specified by:
      set in class AbstractTensor<T extends AbstractCooSemiringTensor<T,U,V>,V extends Semiring<V>[],V extends Semiring<V>>
      Parameters:
      value - New value to set the specified index of this tensor to.
      target - Index 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 target is not within the bounds of this tensor.

    • flatten

      public T flatten()
      Flattens tensor to single dimension while preserving order of data.
      Specified by:
      flatten in class AbstractTensor<T extends AbstractCooSemiringTensor<T,U,V>,V extends Semiring<V>[],V extends Semiring<V>>
      Returns:
      The flattened tensor.
      See Also:

    • flatten

      public T flatten(int axis)
      Flattens a tensor along the specified axis. Unlike flatten()
      Specified by:
      flatten in class AbstractTensor<T extends AbstractCooSemiringTensor<T,U,V>,V extends Semiring<V>[],V extends Semiring<V>>
      Parameters:
      axis - Axis along which to flatten tensor.
      Throws:
      ArrayIndexOutOfBoundsException - If the axis is not positive or larger than this.{@link #getRank()}-1.
      See Also:

    • reshape

      public T reshape(Shape newShape)
      Copies and reshapes this tensor.
      Specified by:
      reshape in class AbstractTensor<T extends AbstractCooSemiringTensor<T,U,V>,V extends Semiring<V>[],V extends Semiring<V>>
      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.

    • sortIndices

      public void sortIndices()
      Sorts the indices of this tensor in lexicographical order while maintaining the associated value for each index.

    • toDense

      public U toDense()
      Converts this COO tensor to an equivalent dense tensor.
      Returns:
      A dense tensor which is equivalent to this COO tensor.
      Throws:
      ArithmeticException - If the number of data in the dense tensor exceeds 2,147,483,647.

    • coalesce

      public T coalesce()
      Coalesces this sparse COO tensor. An uncoalesced tensor is a sparse tensor with multiple data for a single index. This method will ensure that each index only has one non-zero value by summing duplicated data. If another form of aggregation other than summing is desired, use coalesce(BinaryOperator).
      Returns:
      A new coalesced sparse COO tensor which is equivalent to this COO tensor.
      See Also:

    • coalesce

      public T coalesce(BinaryOperator<V> aggregator)
      Coalesces this sparse COO tensor. An uncoalesced tensor is a sparse tensor with multiple data for a single index. This method will ensure that each index only has one non-zero value by aggregating duplicated data using aggregator.
      Parameters:
      aggregator - Custom aggregation function to combine multiple.
      Returns:
      A new coalesced sparse COO tensor which is equivalent to this COO tensor.
      See Also:

    • dropZeros

      public T dropZeros()
      Drops any explicit zeros in this sparse COO tensor.
      Returns:
      A copy of this COO tensor with any explicitly stored zeros removed.