Class CooFieldVector<T extends Field<T>>

java.lang.Object
org.flag4j.arrays.backend.AbstractTensor<CooFieldVector<T>,T[],T>
org.flag4j.arrays.backend.semiring_arrays.AbstractCooSemiringVector<CooFieldVector<T>,FieldVector<T>,CooFieldMatrix<T>,FieldMatrix<T>,T>
org.flag4j.arrays.backend.ring_arrays.AbstractCooRingVector<CooFieldVector<T>,FieldVector<T>,CooFieldMatrix<T>,FieldMatrix<T>,T>
org.flag4j.arrays.backend.field_arrays.AbstractCooFieldVector<CooFieldVector<T>,FieldVector<T>,CooFieldMatrix<T>,FieldMatrix<T>,T>
org.flag4j.arrays.sparse.CooFieldVector<T>
Type Parameters:
T - The type of elements stored in this vector, constrained by the Field interface.
All Implemented Interfaces:
Serializable, FieldTensorMixin<CooFieldVector<T>,FieldVector<T>,T>, TensorOverField<CooFieldVector<T>,FieldVector<T>,T[],T>, RingTensorMixin<CooFieldVector<T>,FieldVector<T>,T>, TensorOverRing<CooFieldVector<T>,FieldVector<T>,T[],T>, SemiringTensorMixin<CooFieldVector<T>,FieldVector<T>,T>, TensorOverSemiring<CooFieldVector<T>,FieldVector<T>,T[],T>, VectorMixin<CooFieldVector<T>,CooFieldMatrix<T>,FieldMatrix<T>,T>
public class CooFieldVector<T extends Field<T>> extends AbstractCooFieldVector<CooFieldVector<T>,FieldVector<T>,CooFieldMatrix<T>,FieldMatrix<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 Field 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);
 Complex128[] data = {
      new Complex128(1, 2), new Complex128(3, 4), new Complex128(5, 6)
      new Complex128(7, 8), new Complex128(9, 10), new Complex128(11, 12)
 };
 int[] indices = {0, 4, 128, 128, 128, 256};

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

 // Sum vectors.
 CooFieldVector<Complex128> sum = vector.add(vector);

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

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

  • Constructor Details

    • CooFieldVector

      public CooFieldVector(int size, T[] entries, int[] 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.

    • CooFieldVector

      public CooFieldVector(Shape shape, T[] entries, int[] 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 full shape of the vector.

    • CooFieldVector

      public CooFieldVector(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.

    • CooFieldVector

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

  • Method Details

    • unsafeMake

      public static <T extends Field<T>> CooFieldVector<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 Field<T>> CooFieldVector<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 CooFieldVector<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<CooFieldVector<T extends Field<T>>,FieldVector<T extends Field<T>>,CooFieldMatrix<T extends Field<T>>,FieldMatrix<T extends Field<T>>,T extends Field<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 FieldVector<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<CooFieldVector<T extends Field<T>>,FieldVector<T extends Field<T>>,CooFieldMatrix<T extends Field<T>>,FieldMatrix<T extends Field<T>>,T extends Field<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 FieldMatrix<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<CooFieldVector<T extends Field<T>>,FieldVector<T extends Field<T>>,CooFieldMatrix<T extends Field<T>>,FieldMatrix<T extends Field<T>>,T extends Field<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 CooFieldVector<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<CooFieldVector<T extends Field<T>>,FieldVector<T extends Field<T>>,CooFieldMatrix<T extends Field<T>>,FieldMatrix<T extends Field<T>>,T extends Field<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 CooFieldMatrix<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<CooFieldVector<T extends Field<T>>,FieldVector<T extends Field<T>>,CooFieldMatrix<T extends Field<T>>,FieldMatrix<T extends Field<T>>,T extends Field<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 CooFieldVector<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<CooFieldVector<T extends Field<T>>,FieldVector<T extends Field<T>>,T extends Field<T>[],T extends Field<T>>
      Specified by:
      makeLikeTensor in class AbstractTensor<CooFieldVector<T extends Field<T>>,T extends Field<T>[],T extends Field<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 CooFieldMatrix<T> toMatrix(boolean columVector)
      Converts a vector to an equivalent matrix representing either a row or column vector.
      Specified by:
      toMatrix in interface VectorMixin<CooFieldVector<T extends Field<T>>,CooFieldMatrix<T extends Field<T>>,FieldMatrix<T extends Field<T>>,T extends Field<T>>
      Overrides:
      toMatrix in class AbstractCooSemiringVector<CooFieldVector<T extends Field<T>>,FieldVector<T extends Field<T>>,CooFieldMatrix<T extends Field<T>>,FieldMatrix<T extends Field<T>>,T extends Field<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 CooFieldTensor<T> toTensor()
      Converts this matrix to an equivalent rank 1 tensor.
      Specified by:
      toTensor in class AbstractCooSemiringVector<CooFieldVector<T extends Field<T>>,FieldVector<T extends Field<T>>,CooFieldMatrix<T extends Field<T>>,FieldMatrix<T extends Field<T>>,T extends Field<T>>
      Returns:
      A tensor which is equivalent to this matrix.

    • toTensor

      public CooFieldTensor<T> toTensor(Shape newShape)
      Converts this vector to an equivalent tensor with the specified shape.
      Specified by:
      toTensor in class AbstractCooSemiringVector<CooFieldVector<T extends Field<T>>,FieldVector<T extends Field<T>>,CooFieldMatrix<T extends Field<T>>,FieldMatrix<T extends Field<T>>,T extends Field<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

    • 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.