Class CooFieldTensor<T extends Field<T>>

java.lang.Object
org.flag4j.arrays.backend.AbstractTensor<CooFieldTensor<T>,T[],T>
org.flag4j.arrays.backend.semiring_arrays.AbstractCooSemiringTensor<CooFieldTensor<T>,FieldTensor<T>,T>
org.flag4j.arrays.backend.ring_arrays.AbstractCooRingTensor<CooFieldTensor<T>,FieldTensor<T>,T>
org.flag4j.arrays.backend.field_arrays.AbstractCooFieldTensor<CooFieldTensor<T>,FieldTensor<T>,T>
org.flag4j.arrays.sparse.CooFieldTensor<T>
Type Parameters:
T - The type of elements stored in this tensor, constrained by the Field interface.
All Implemented Interfaces:
Serializable, FieldTensorMixin<CooFieldTensor<T>,CooFieldTensor<T>,T>, TensorOverField<CooFieldTensor<T>,CooFieldTensor<T>,T[],T>, RingTensorMixin<CooFieldTensor<T>,CooFieldTensor<T>,T>, TensorOverRing<CooFieldTensor<T>,CooFieldTensor<T>,T[],T>, SemiringTensorMixin<CooFieldTensor<T>,CooFieldTensor<T>,T>, TensorOverSemiring<CooFieldTensor<T>,CooFieldTensor<T>,T[],T>
public class CooFieldTensor<T extends Field<T>> extends AbstractCooFieldTensor<CooFieldTensor<T>,FieldTensor<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 Field 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)
 Complex128[] data = {
      new Complex128(1, 2), new Complex128(3, 4), new Complex128(5, 6), new Complex128(7, 8)
 };
 int[][] indices = {
     {0, 1, 2, 3},
     {1, 2, 3, 4},
     {12, 22, 40, 3},
     {12, 22, 41, 0}
 };

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

 // Compute element-wise sum.
 CooFieldTensor<Complex128> sum = tensor.add(tensor);

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

 // Reshape tensor.
 CooFieldTensor<Complex128> reshaped = tensor.reshape(15, 150, 45)

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

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

  • Constructor Details

    • CooFieldTensor

      public CooFieldTensor(Shape shape, T[] entries, int[][] indices)
      creates a tensor with the specified data and shape.
      Parameters:
      shape - shape of this tensor.
      entries - 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 -

    • CooFieldTensor

      public CooFieldTensor(Shape shape, List<T> entries, List<int[]> indices)
      Creates a tensor with the specified data and shape.
      Parameters:
      shape - Shape of this tensor.
      entries - 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 CooFieldTensor<T> makeLikeTensor(Shape shape, T[] entries, 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<CooFieldTensor<T extends Field<T>>,FieldTensor<T extends Field<T>>,T extends Field<T>>
      Parameters:
      shape - Shape of the tensor to construct.
      entries - 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.

    • set

      public CooFieldTensor<T> set(T value, int... index)
      Sets the element of this tensor at the specified indices.
      Overrides:
      set in class AbstractCooSemiringTensor<CooFieldTensor<T extends Field<T>>,FieldTensor<T extends Field<T>>,T extends Field<T>>
      Parameters:
      value - New value to set the specified index of this tensor to.
      index - Indices of the element to set.
      Returns:
      A copy of this tensor with the updated value is returned.
      Throws:
      IndexOutOfBoundsException - If indices is not within the bounds of this tensor.

    • makeLikeTensor

      public CooFieldTensor<T> makeLikeTensor(Shape shape, T[] entries)
      Constructs a sparse tensor of the same type as this tensor with the same indices as this sparse tensor and with the provided the shape and data.
      Specified by:
      makeLikeTensor in interface TensorOverSemiring<CooFieldTensor<T extends Field<T>>,CooFieldTensor<T extends Field<T>>,T extends Field<T>[],T extends Field<T>>
      Specified by:
      makeLikeTensor in class AbstractTensor<CooFieldTensor<T extends Field<T>>,T extends Field<T>[],T extends Field<T>>
      Parameters:
      shape - Shape of the sparse tensor to construct.
      entries - Entries of the spares tensor to construct.
      Returns:
      A sparse tensor of the same type as this tensor with the same indices as this sparse tensor and with the provided the shape and data.

    • makeLikeTensor

      public CooFieldTensor<T> makeLikeTensor(Shape shape, List<T> entries, List<int[]> indices)
      Constructs a sparse tensor of the same type as this tensor with the given the shape, non-zero data, and non-zero indices.
      Specified by:
      makeLikeTensor in class AbstractCooSemiringTensor<CooFieldTensor<T extends Field<T>>,FieldTensor<T extends Field<T>>,T extends Field<T>>
      Parameters:
      shape - Shape of the sparse tensor to construct.
      entries - Non-zero data of the sparse tensor to construct.
      indices - Non-zero indices of the sparse tensor to construct.
      Returns:
      A sparse tensor of the same type as this tensor with the given the shape and data.

    • makeLikeDenseTensor

      public FieldTensor<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<CooFieldTensor<T extends Field<T>>,FieldTensor<T extends Field<T>>,T extends Field<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.

    • toVector

      public FieldVector<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 CooFieldMatrix<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 CooFieldMatrix<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 CooFieldTensor. 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.