Class CooRingVector<T extends Ring<T>>

java.lang.Object
org.flag4j.arrays.backend.AbstractTensor<CooRingVector<T>,T[],T>
org.flag4j.arrays.backend.semiring_arrays.AbstractCooSemiringVector<CooRingVector<T>,RingVector<T>,CooRingMatrix<T>,RingMatrix<T>,T>
org.flag4j.arrays.backend.ring_arrays.AbstractCooRingVector<CooRingVector<T>,RingVector<T>,CooRingMatrix<T>,RingMatrix<T>,T>
org.flag4j.arrays.sparse.CooRingVector<T>
Type Parameters:
T - The type of elements stored in this vector, constrained by the Ring interface.
All Implemented Interfaces:
Serializable, RingTensorMixin<CooRingVector<T>,RingVector<T>,T>, TensorOverRing<CooRingVector<T>,RingVector<T>,T[],T>, SemiringTensorMixin<CooRingVector<T>,RingVector<T>,T>, TensorOverSemiring<CooRingVector<T>,RingVector<T>,T[],T>, VectorMixin<CooRingVector<T>,CooRingMatrix<T>,RingMatrix<T>,T>
public class CooRingVector<T extends Ring<T>> extends AbstractCooRingVector<CooRingVector<T>,RingVector<T>,CooRingMatrix<T>,RingMatrix<T>,T>
Represents a sparse vector whose non-zero elements are stored in Coordinate List (COO) format, with all data elements belonging to a specified Ring type.

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

A sparse COO vector is stored as:

The total number of non-zero elements (AbstractCooSemiringVector.nnz) and the shape/size is fixed for a given instance, but the values in AbstractTensor.data and their corresponding AbstractCooSemiringVector.indices may be updated. Many operations assume that the indices are sorted lexicographically, but this is not strictly enforced. All provided operations preserve the lexicographical sorting of indices. If there is any doubt about the ordering of indices, use AbstractCooSemiringVector.sortIndices() to ensure they are sorted. COO tensors may also store multiple entries for the same index (referred to as an uncoalesced tensor). To combine all duplicated entries use AbstractCooSemiringVector.coalesce() or AbstractCooSemiringVector.coalesce(BinaryOperator).

COO vectors are optimized for "hyper-sparse" scenarios 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:


 // shape, data, and indices for COO vector.
 Shape shape = new Shape(512);
 RealInt32[] data = {
      new RealInt32(1), new RealInt32(2), new RealInt32(3),
      new RealInt32(4), new RealInt32(5), new RealInt32(6)
 };
 int[] indices = {0, 4, 128, 128, 128, 256};

 // Create COO vector.
 CooRingVector<RealInt32> vector = new CooRingVector(shape, data, indices);

 // Sum vectors.
 CooRingVector<RealInt32> sum = vector.add(vector);

 // Compute vector inner product.
 RealInt32 prod = vector.inner(vector);

 // Compute vector outer product.
 RingMatrix<RealInt32> prod = vector.outer(vector);
See Also:

  • Constructor Details

    • CooRingVector

      public CooRingVector(int size, T[] entries, int[] indices)
      Creates a tensor with the specified data and shape.
      Parameters:
      size -
      entries - Entries 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 -

    • CooRingVector

      public CooRingVector(Shape shape, T[] entries, int[] indices)
      Creates a tensor with the specified data and shape.
      Parameters:
      entries - Entries 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 -
      size -

    • CooRingVector

      public CooRingVector(Shape shape, List<T> entries, List<Integer> indices)
      Creates sparse COO vector with the specified size, non-zero data, and non-zero indices.
      Parameters:
      entries - The non-zero data of this vector.
      indices - The indices of the non-zero values.
      Shape - The shape of this vector. Must be rank-1.

    • CooRingVector

      public CooRingVector(int size)
      Creates a zero vector of the specified size.

    • CooRingVector

      public CooRingVector(int size, List<T> entries, List<Integer> indices)
      Creates sparse COO vector with the specified size, non-zero data, and non-zero indices.
      Parameters:
      size - The size of this vector.
      entries - The non-zero data of this vector.
      indices - The indices of the non-zero values.

  • Method Details

    • unsafeMake

      public static <T extends Ring<T>> CooRingVector<T> unsafeMake(int size, T[] data, int[] indices)

      Factory to construct a COO vector which bypasses any validation checks on the data and indices.

      Warning: This method should be used with extreme caution. It primarily exists for internal use. Only use this factory if you are 100% certain the parameters are valid as some methods may throw exceptions or exhibit undefined behavior.

      Parameters:
      size - The full size of the COO vector.
      data - The non-zero entries of the COO vector.
      indices - The non-zero indices of the COO vector.
      Returns:
      A COO vector constructed from the provided parameters.

    • unsafeMake

      public static <T extends Ring<T>> CooRingVector<T> unsafeMake(Shape shape, T[] data, int[] indices)

      Factory to construct a COO vector which bypasses any validation checks on the data and indices.

      Warning: This method should be used with extreme caution. It primarily exists for internal use. Only use this factory if you are 100% certain the parameters are valid as some methods may throw exceptions or exhibit undefined behavior.

      Parameters:
      data - The non-zero entries of the COO vector.
      indices - The non-zero indices of the COO vector.
      Shape - Full shape of the COO vector. Assumed to be rank 1 (this is not enforced).
      Returns:
      A COO vector constructed from the provided parameters.

    • makeLikeTensor

      public CooRingVector<T> makeLikeTensor(Shape shape, T[] entries, int[] indices)
      Constructs a sparse COO vector of the same type as this vector with the specified non-zero data and indices.
      Specified by:
      makeLikeTensor in class AbstractCooSemiringVector<CooRingVector<T extends Ring<T>>,RingVector<T extends Ring<T>>,CooRingMatrix<T extends Ring<T>>,RingMatrix<T extends Ring<T>>,T extends Ring<T>>
      Parameters:
      shape - Shape of the vector to construct.
      entries - Non-zero data 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 data and indices.

    • makeLikeDenseTensor

      public RingVector<T> makeLikeDenseTensor(Shape shape, T... entries)
      Constructs a dense vector of a similar type as this vector with the specified shape and data.
      Specified by:
      makeLikeDenseTensor in class AbstractCooSemiringVector<CooRingVector<T extends Ring<T>>,RingVector<T extends Ring<T>>,CooRingMatrix<T extends Ring<T>>,RingMatrix<T extends Ring<T>>,T extends Ring<T>>
      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 data.

    • makeLikeDenseMatrix

      public RingMatrix<T> makeLikeDenseMatrix(Shape shape, T... entries)
      Constructs a dense matrix of a similar type as this vector with the specified shape and data.
      Specified by:
      makeLikeDenseMatrix in class AbstractCooSemiringVector<CooRingVector<T extends Ring<T>>,RingVector<T extends Ring<T>>,CooRingMatrix<T extends Ring<T>>,RingMatrix<T extends Ring<T>>,T extends Ring<T>>
      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 data.

    • makeLikeTensor

      public CooRingVector<T> makeLikeTensor(Shape shape, List<T> entries, List<Integer> indices)
      Constructs a COO vector with the specified shape, non-zero data, and non-zero indices.
      Specified by:
      makeLikeTensor in class AbstractCooSemiringVector<CooRingVector<T extends Ring<T>>,RingVector<T extends Ring<T>>,CooRingMatrix<T extends Ring<T>>,RingMatrix<T extends Ring<T>>,T extends Ring<T>>
      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 data, and non-zero indices.

    • makeLikeMatrix

      public CooRingMatrix<T> makeLikeMatrix(Shape shape, T[] entries, int[] rowIndices, int[] colIndices)
      Constructs a COO matrix with the specified shape, non-zero data, and row and column indices.
      Specified by:
      makeLikeMatrix in class AbstractCooSemiringVector<CooRingVector<T extends Ring<T>>,RingVector<T extends Ring<T>>,CooRingMatrix<T extends Ring<T>>,RingMatrix<T extends Ring<T>>,T extends Ring<T>>
      Parameters:
      shape - Shape of the matrix to construct.
      entries - Non-zero data 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 data, and non-zero row/col indices.

    • makeLikeTensor

      public CooRingVector<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<CooRingVector<T extends Ring<T>>,RingVector<T extends Ring<T>>,T extends Ring<T>[],T extends Ring<T>>
      Specified by:
      makeLikeTensor in class AbstractTensor<CooRingVector<T extends Ring<T>>,T extends Ring<T>[],T extends Ring<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.

    • equals

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

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toMatrix

      public CooRingMatrix<T> toMatrix(boolean columVector)
      Converts a vector to an equivalent matrix representing either a row or column vector.
      Specified by:
      toMatrix in interface VectorMixin<CooRingVector<T extends Ring<T>>,CooRingMatrix<T extends Ring<T>>,RingMatrix<T extends Ring<T>>,T extends Ring<T>>
      Overrides:
      toMatrix in class AbstractCooSemiringVector<CooRingVector<T extends Ring<T>>,RingVector<T extends Ring<T>>,CooRingMatrix<T extends Ring<T>>,RingMatrix<T extends Ring<T>>,T extends Ring<T>>
      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.

    • toTensor

      public CooRingTensor<T> toTensor()
      Converts this matrix to an equivalent rank 1 tensor.
      Specified by:
      toTensor in class AbstractCooSemiringVector<CooRingVector<T extends Ring<T>>,RingVector<T extends Ring<T>>,CooRingMatrix<T extends Ring<T>>,RingMatrix<T extends Ring<T>>,T extends Ring<T>>
      Returns:
      A tensor which is equivalent to this matrix.

    • toTensor

      public CooRingTensor<T> toTensor(Shape newShape)
      Converts this vector to an equivalent tensor with the specified shape.
      Specified by:
      toTensor in class AbstractCooSemiringVector<CooRingVector<T extends Ring<T>>,RingVector<T extends Ring<T>>,CooRingMatrix<T extends Ring<T>>,RingMatrix<T extends Ring<T>>,T extends Ring<T>>
      Parameters:
      newShape - New shape for the tensor. Can be any rank but must be broadcastable to this.shape.
      Returns:
      A tensor equivalent to this matrix which has been reshaped to newShape

    • abs

      public CooVector abs()
      Computes the element-wise absolute value of this tensor.
      Returns:
      The element-wise absolute value of this tensor.

    • toString

      public String toString()
      Formats this tensor as a human-readable string. Specifically, a string containing the shape and flatten data of this tensor.
      Overrides:
      toString in class Object
      Returns:
      A human-readable string representing this tensor.