Class CooFieldMatrix<T extends Field<T>>

java.lang.Object
org.flag4j.arrays.backend.AbstractTensor<CooFieldMatrix<T>,T[],T>
org.flag4j.arrays.backend.semiring_arrays.AbstractCooSemiringMatrix<CooFieldMatrix<T>,FieldMatrix<T>,CooFieldVector<T>,T>
org.flag4j.arrays.backend.ring_arrays.AbstractCooRingMatrix<CooFieldMatrix<T>,FieldMatrix<T>,CooFieldVector<T>,T>
org.flag4j.arrays.backend.field_arrays.AbstractCooFieldMatrix<CooFieldMatrix<T>,FieldMatrix<T>,CooFieldVector<T>,T>
org.flag4j.arrays.sparse.CooFieldMatrix<T>
Type Parameters:
T - The type of elements stored in this matrix, constrained by the Field interface.
All Implemented Interfaces:
Serializable, FieldTensorMixin<CooFieldMatrix<T>,FieldMatrix<T>,T>, TensorOverField<CooFieldMatrix<T>,FieldMatrix<T>,T[],T>, MatrixMixin<CooFieldMatrix<T>,FieldMatrix<T>,CooFieldVector<T>,T>, RingTensorMixin<CooFieldMatrix<T>,FieldMatrix<T>,T>, TensorOverRing<CooFieldMatrix<T>,FieldMatrix<T>,T[],T>, SemiringTensorMixin<CooFieldMatrix<T>,FieldMatrix<T>,T>, TensorOverSemiring<CooFieldMatrix<T>,FieldMatrix<T>,T[],T>
public class CooFieldMatrix<T extends Field<T>> extends AbstractCooFieldMatrix<CooFieldMatrix<T>,FieldMatrix<T>,CooFieldVector<T>,T>

Instances of this class represent a sparse matrix 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 matrix data as a list of coordinates (row and column indices) coupled with their corresponding non-zero values, rather than allocating memory for every element in the full matrix shape. This allows efficient representation and manipulation of large matrices containing a substantial number of zeros.

COO Representation:

A sparse COO matrix is stored as:

The total number of non-zero elements (AbstractCooSemiringMatrix.nnz) and the shape are fixed for a given instance, but the values in AbstractTensor.data and their corresponding AbstractCooSemiringMatrix.rowIndices and AbstractCooSemiringMatrix.colIndices may be updated. Many operations assume that the indices are sorted lexicographically by row, and then by column, 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 AbstractCooSemiringMatrix.sortIndices() to ensure they 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 AbstractCooSemiringMatrix.coalesce() or AbstractCooSemiringMatrix.coalesce(BinaryOperator).

COO matrices 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 matrix.
 Shape shape = new Shape(512, 1024);
 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[] rowIndices = {0, 4, 128, 128, 128, 256};
 int[] colIndices = {16, 2, 5, 512, 1000, 28};

 // Create COO matrix.
 CooFieldMatrix<Complex128> matrix = new CooFieldMatrix<>(
      shape, data, rowIndices, colIndices
 );

 // Sum matrices.
 CooFieldMatrix<Complex128> sum = matrix.add(matrix);

 // Multiply matrix to it's Hermitian transpose.
 FieldMatrix<Complex128> prod = matrix.mult(matrix.H());
 prod = matrix.multTranspose(matrix);
See Also:

  • Constructor Details

    • CooFieldMatrix

      public CooFieldMatrix(Shape shape, T[] entries, int[] rowIndices, int[] colIndices)
      Creates a sparse coo matrix with the specified non-zero data, non-zero indices, and shape.
      Parameters:
      shape - Shape of this tensor.
      entries - Non-zero data of this sparse matrix.
      rowIndices - Non-zero row indices of this sparse matrix.
      colIndices - Non-zero column indies of this sparse matrix.

    • CooFieldMatrix

      public CooFieldMatrix(Shape shape, List<T> entries, List<Integer> rowIndices, List<Integer> colIndices)
      Creates a sparse coo matrix with the specified non-zero data, non-zero indices, and shape.
      Parameters:
      shape - Shape of this tensor.
      entries - Non-zero data of this sparse matrix.
      rowIndices - Non-zero row indices of this sparse matrix.
      colIndices - Non-zero column indies of this sparse matrix.

    • CooFieldMatrix

      public CooFieldMatrix(int rows, int cols, T[] entries, int[] rowIndices, int[] colIndices)
      Creates a sparse coo matrix with the specified non-zero data, non-zero indices, and shape.
      Parameters:
      rows - Rows in the coo matrix.
      cols - Columns in the coo matrix.
      entries - Non-zero data of this sparse matrix.
      rowIndices - Non-zero row indices of this sparse matrix.
      colIndices - Non-zero column indies of this sparse matrix.

    • CooFieldMatrix

      public CooFieldMatrix(int rows, int cols, List<T> entries, List<Integer> rowIndices, List<Integer> colIndices)
      Creates a sparse coo matrix with the specified non-zero data, non-zero indices, and shape.
      Parameters:
      rows - Rows in the coo matrix.
      cols - Columns in the coo matrix.
      entries - Non-zero data of this sparse matrix.
      rowIndices - Non-zero row indices of this sparse matrix.
      colIndices - Non-zero column indies of this sparse matrix.

  • Method Details

    • makeLikeTensor

      public CooFieldMatrix<T> makeLikeTensor(Shape shape, T[] entries, int[] rowIndices, int[] colIndices)
      Constructs a sparse COO tensor of the same type as this tensor with the specified non-zero data and indices.
      Specified by:
      makeLikeTensor in class AbstractCooSemiringMatrix<CooFieldMatrix<T extends Field<T>>,FieldMatrix<T extends Field<T>>,CooFieldVector<T extends Field<T>>,T extends Field<T>>
      Parameters:
      shape - Shape of the matrix.
      entries - Non-zero data of the matrix.
      rowIndices - Non-zero row indices of the matrix.
      colIndices - Non-zero column indices of the matrix.
      Returns:
      A sparse COO tensor of the same type as this tensor with the specified non-zero data and indices.

    • makeLikeTensor

      public CooFieldMatrix<T> makeLikeTensor(Shape shape, List<T> entries, List<Integer> rowIndices, List<Integer> colIndices)
      Constructs a COO matrix with the specified shape, non-zero data, and non-zero indices.
      Specified by:
      makeLikeTensor in class AbstractCooSemiringMatrix<CooFieldMatrix<T extends Field<T>>,FieldMatrix<T extends Field<T>>,CooFieldVector<T extends Field<T>>,T extends Field<T>>
      Parameters:
      shape - Shape of the matrix.
      entries - Non-zero values of the matrix.
      rowIndices - Non-zero row indices of the matrix.
      colIndices - Non-zero column indices of the matrix.
      Returns:
      A COO matrix with the specified shape, non-zero data, and non-zero indices.

    • makeLikeVector

      public CooFieldVector<T> makeLikeVector(Shape shape, T[] entries, int[] indices)
      Constructs a sparse COO vector of a similar type to this COO matrix.
      Specified by:
      makeLikeVector in class AbstractCooSemiringMatrix<CooFieldMatrix<T extends Field<T>>,FieldMatrix<T extends Field<T>>,CooFieldVector<T extends Field<T>>,T extends Field<T>>
      Parameters:
      shape - Shape of the vector. Must be rank 1.
      entries - Non-zero data of the COO vector.
      indices - Non-zero indices of the COO vector.
      Returns:
      A sparse COO vector of a similar type to this COO matrix.

    • makeLikeDenseTensor

      public FieldMatrix<T> makeLikeDenseTensor(Shape shape, T[] entries)
      Constructs a dense tensor with the specified shape and data which is a similar type to this sparse tensor.
      Specified by:
      makeLikeDenseTensor in class AbstractCooSemiringMatrix<CooFieldMatrix<T extends Field<T>>,FieldMatrix<T extends Field<T>>,CooFieldVector<T extends Field<T>>,T extends Field<T>>
      Parameters:
      shape - Shape of the dense tensor.
      entries - Entries of the dense tensor.
      Returns:
      A dense tensor with the specified shape and data which is a similar type to this sparse tensor.

    • makeLikeCsrMatrix

      public CsrFieldMatrix<T> makeLikeCsrMatrix(Shape shape, T[] entries, int[] rowPointers, int[] colIndices)
      Constructs a sparse CSR matrix of a similar type to this sparse COO matrix.
      Specified by:
      makeLikeCsrMatrix in class AbstractCooFieldMatrix<CooFieldMatrix<T extends Field<T>>,FieldMatrix<T extends Field<T>>,CooFieldVector<T extends Field<T>>,T extends Field<T>>
      Parameters:
      shape - Shape of the CSR matrix to construct.
      entries - Non-zero data of the CSR matrix.
      rowPointers - Non-zero row pointers of the CSR matrix.
      colIndices - Non-zero column indices of the CSR matrix.
      Returns:
      A CSR matrix of a similar type to this sparse COO matrix.

    • makeLikeTensor

      public CooFieldMatrix<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<CooFieldMatrix<T extends Field<T>>,FieldMatrix<T extends Field<T>>,T extends Field<T>[],T extends Field<T>>
      Specified by:
      makeLikeTensor in class AbstractTensor<CooFieldMatrix<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.

    • tensorDot

      public FieldTensor<T> tensorDot(CooFieldMatrix<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.

      For matrices, calling this.tensorDot(src2, new int[]{1}, new int[]{0}) is equivalent to matrix multiplication. However, it is highly recommended to use mult(CooFieldVector) instead.

      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.

    • toCsr

      public CsrFieldMatrix<T> toCsr()

      Converts this sparse COO matrix to an equivalent compressed sparse row (CSR) matrix.

      It is often easier and more efficient to construct a matrix in COO format first then convert to a CSR matrix for efficient computations.

      Overrides:
      toCsr in class AbstractCooFieldMatrix<CooFieldMatrix<T extends Field<T>>,FieldMatrix<T extends Field<T>>,CooFieldVector<T extends Field<T>>,T extends Field<T>>
      Returns:
      A CSR matrix equivalent to this COO matrix.

    • toTensor

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

    • mult

      public FieldVector<T> mult(CooFieldVector<T> b)
      Computes the matrix-vector multiplication of a vector with this matrix.
      Parameters:
      b - Vector in the matrix-vector multiplication.
      Returns:
      The result of multiplying this matrix with b.
      Throws:
      LinearAlgebraException - If the number of columns in this matrix do not equal the size of b.

    • accept

      public <R> R accept(MatrixVisitor<R> visitor)
      Accepts a visitor that implements the MatrixVisitor interface. This method is part of the "Visitor Pattern" and allows operations to be performed on the matrix without modifying the matrix's class directly.
      Type Parameters:
      R - The return type of the visitor's operation.
      Parameters:
      visitor - The visitor implementing the operation to be performed.
      Returns:
      The result of the visitor's operation, typically another matrix or a scalar value.
      Throws:
      NullPointerException - if the visitor is null.

    • equals

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

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Formats this sparse matrix as a human-readable string.
      Overrides:
      toString in class Object
      Returns:
      A human-readable string representing this sparse matrix.