Class CooSemiringTensor<T extends Semiring<T>>

java.lang.Object
org.flag4j.arrays.backend.AbstractTensor<CooSemiringTensor<T>,T[],T>
org.flag4j.arrays.backend.semiring_arrays.AbstractCooSemiringTensor<CooSemiringTensor<T>,SemiringTensor<T>,T>
org.flag4j.arrays.sparse.CooSemiringTensor<T>
Type Parameters:
T - The type of elements stored in this tensor, constrained by the Semiring interface.
All Implemented Interfaces:
Serializable, SemiringTensorMixin<CooSemiringTensor<T>,CooSemiringTensor<T>,T>, TensorOverSemiring<CooSemiringTensor<T>,CooSemiringTensor<T>,T[],T>
public class CooSemiringTensor<T extends Semiring<T>> extends AbstractCooSemiringTensor<CooSemiringTensor<T>,SemiringTensor<T>,T>
Represents a sparse tensor whose non-zero elements are stored in Coordinate List (COO) format, with all data elements belonging to a specified Semiring type.

The COO format stores sparse data as a list of coordinates (indices) coupled with their corresponding non-zero values, rather than allocating memory for every element in the full tensor shape. This allows efficient representation and manipulation of high-dimensional tensors that contain a substantial number of zeros.

A sparse COO tensor is stored as:

The total number of non-zero elements (AbstractCooSemiringTensor.nnz) and the shape are fixed for a given instance, but the specific values in AbstractTensor.data and their corresponding AbstractCooSemiringTensor.indices may be updated. Many operations assume the indices are sorted lexicographically in row-major order (i.e., the last dimension’s index varies fastest), although this is not explicitly enforced. All provided operations will preserve lexicographically row-major sorting of the indices. If there is any doubt that the indices of this tensor may not be sorted, use AbstractCooSemiringTensor.sortIndices() to insure the indices are explicitly sorted. COO tensors may also store multiple entries for the same index (referred to as an uncoalesced tensor). To combine all duplicated entries use AbstractCooSemiringTensor.coalesce() or AbstractCooSemiringTensor.coalesce(BinaryOperator).

COO tensors are optimized for "hyper-sparse" tensors where the proportion of non-zero elements is extremely low, offering significant memory savings and potentially more efficient computational operations than equivalent dense representations.

Example Usage:


 // Define shape, data, and indices.
 Shape shape = new Shape(15, 30, 45, 5)
 BoolSemiring[] data = {
      new BoolSemiring(true), new BoolSemiring(false), new BoolSemiring(false), new BoolSemiring(true)
 };
 int[][] indices = {
     {0, 1, 2, 3},
     {1, 2, 3, 4},
     {12, 22, 40, 3},
     {12, 22, 41, 0}
 };

 // Create COO tensor.
 CooSemiringTensor<BoolSemiring> tensor = new CooSemiringTensor(shape, data, indices);

 // Compute element-wise sum.
 CooSemiringTensor<BoolSemiring> sum = tensor.add(tensor);

 // Sum of all non-zero entries.
 RealInt32 = tensor.sum();

 // Reshape tensor.
 CooSemiringTensor<BoolSemiring> reshaped = tensor.reshape(15, 150, 45)

 // Compute tensor dot product (result is 5-by-5 dense tensor).
 SemiringTensor<BoolSemiring> dot = tensor.dot(tensor,
      new int[]{0, 1, 2},
      new int[]{0, 1, 2}
 );

 // Compute tensor transposes.
 CooSemiringTensor<RBoolSemiring> transpose = tensor.T();
 transpose = tensor.T(0, 1);
 transpose = tensor.T(1, 3, 0, 2);
See Also:

  • Constructor Details

    • CooSemiringTensor

      public CooSemiringTensor(Shape shape, T[] 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.
      indices -

    • CooSemiringTensor

      public CooSemiringTensor(Shape shape, List<T> data, List<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.
      indices -

  • Method Details

    • makeLikeTensor

      public CooSemiringTensor<T> makeLikeTensor(Shape shape, T[] data, int[][] indices)
      Constructs a tensor of the same type as this tensor with the specified shape and non-zero data.
      Specified by:
      makeLikeTensor in class AbstractCooSemiringTensor<CooSemiringTensor<T extends Semiring<T>>,SemiringTensor<T extends Semiring<T>>,T extends Semiring<T>>
      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 CooSemiringTensor<T> makeLikeTensor(Shape shape, List<T> data, List<int[]> indices)
      Constructs a tensor of the same type as this tensor with the specified shape and non-zero data.
      Specified by:
      makeLikeTensor in class AbstractCooSemiringTensor<CooSemiringTensor<T extends Semiring<T>>,SemiringTensor<T extends Semiring<T>>,T extends Semiring<T>>
      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 SemiringTensor<T> makeLikeDenseTensor(Shape shape, T[] entries)
      Constructs a dense tensor that is a similar type as this sparse COO tensor.
      Specified by:
      makeLikeDenseTensor in class AbstractCooSemiringTensor<CooSemiringTensor<T extends Semiring<T>>,SemiringTensor<T extends Semiring<T>>,T extends Semiring<T>>
      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.

    • makeLikeTensor

      public CooSemiringTensor<T> makeLikeTensor(Shape shape, T[] entries)
      Constructs a tensor of the same type as this tensor with the given the shape and data. The resulting tensor will also have the same non-zero indices as this tensor.
      Specified by:
      makeLikeTensor in interface TensorOverSemiring<CooSemiringTensor<T extends Semiring<T>>,CooSemiringTensor<T extends Semiring<T>>,T extends Semiring<T>[],T extends Semiring<T>>
      Specified by:
      makeLikeTensor in class AbstractTensor<CooSemiringTensor<T extends Semiring<T>>,T extends Semiring<T>[],T extends Semiring<T>>
      Parameters:
      shape - Shape of the tensor to construct.
      entries - Entries of the tensor to construct.
      Returns:
      A tensor of the same type and with the same non-zero indices as this tensor with the given the shape and data.

    • toVector

      public SemiringVector<T> toVector()
      Converts this tensor to an equivalent vector. If this tensor is not rank 1, then it will be flattened.
      Returns:
      A vector equivalent of this tensor.

    • toMatrix

      public CooSemiringMatrix<T> toMatrix(Shape matShape)
      Converts this tensor to a matrix with the specified shape.
      Parameters:
      matShape - Shape of the resulting matrix. Must be broadcastable with the shape of this tensor.
      Returns:
      A matrix of shape matShape with the values of this tensor.
      Throws:
      LinearAlgebraException - If matShape is not of rank 2.

    • toMatrix

      public CooSemiringMatrix<T> toMatrix()
      Converts this tensor to an equivalent matrix.
      Returns:
      If this tensor is rank 2, then the equivalent matrix will be returned. If the tensor is rank 1, then a matrix with a single row will be returned. If the rank of this tensor is larger than 2, it will be flattened to a single row.

    • equals

      public boolean equals(Object object)
      Checks if an object is equal to this tensor object.
      Overrides:
      equals in class Object
      Parameters:
      object - Object to check equality with this tensor.
      Returns:
      True if the two tensors have the same shape, are numerically equivalent, and are of type CooSemiringTensor. False otherwise.

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()

      Formats this sparse COO tensor as a human-readable string specifying the full shape, non-zero data, and non-zero indices.

      Overrides:
      toString in class Object
      Returns:
      A human-readable string specifying the full shape, non-zero data, and non-zero indices of this tensor.