Class CooRingMatrix<T extends Ring<T>>

Type Parameters:
T - The type of elements stored in this matrix, constrained by the Ring interface.
All Implemented Interfaces:
Serializable, MatrixMixin<CooRingMatrix<T>,RingMatrix<T>,CooRingVector<T>,T>, RingTensorMixin<CooRingMatrix<T>,RingMatrix<T>,T>, TensorOverRing<CooRingMatrix<T>,RingMatrix<T>,T[],T>, SemiringTensorMixin<CooRingMatrix<T>,RingMatrix<T>,T>, TensorOverSemiring<CooRingMatrix<T>,RingMatrix<T>,T[],T>

public class CooRingMatrix<T extends Ring<T>> extends AbstractCooRingMatrix<CooRingMatrix<T>,RingMatrix<T>,CooRingVector<T>,T>
Represents a sparse matrix 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 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.


 // shape, data, and indices for COO matrix.
 Shape shape = new Shape(512, 1024);
 RealInt32[] data = {
      new RealInt32(1), new RealInt32(2), new RealInt32(3),
      new RealInt32(4), new RealInt32(5), new RealInt32(6),
 };
 int[] rowIndices = {0, 4, 128, 128, 128, 256};
 int[] colIndices = {16, 2, 5, 512, 1000, 28};

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

 // Sum matrices.
 CooRingMatrix<RealInt32> sum = matrix.add(matrix);

 // Multiply matrix to it's transpose.
 RingMatrix<RealInt32> prod = matrix.mult(matrix.T());
 prod = matrix.multTranspose(matrix);
 
See Also:
  • Constructor Details

    • CooRingMatrix

      public CooRingMatrix(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.
    • CooRingMatrix

      public CooRingMatrix(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.
    • CooRingMatrix

      public CooRingMatrix(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.
    • CooRingMatrix

      public CooRingMatrix(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 CooRingMatrix<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<CooRingMatrix<T extends Ring<T>>,RingMatrix<T extends Ring<T>>,CooRingVector<T extends Ring<T>>,T extends Ring<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 CooRingMatrix<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<CooRingMatrix<T extends Ring<T>>,RingMatrix<T extends Ring<T>>,CooRingVector<T extends Ring<T>>,T extends Ring<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 CooRingVector<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<CooRingMatrix<T extends Ring<T>>,RingMatrix<T extends Ring<T>>,CooRingVector<T extends Ring<T>>,T extends Ring<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 RingMatrix<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<CooRingMatrix<T extends Ring<T>>,RingMatrix<T extends Ring<T>>,CooRingVector<T extends Ring<T>>,T extends Ring<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 CsrRingMatrix<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 AbstractCooRingMatrix<CooRingMatrix<T extends Ring<T>>,RingMatrix<T extends Ring<T>>,CooRingVector<T extends Ring<T>>,T extends Ring<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.
    • toTensor

      public CooRingTensor<T> toTensor()
      Converts this matrix to an equivalent rank 2 tensor.
      Specified by:
      toTensor in class AbstractCooRingMatrix<CooRingMatrix<T extends Ring<T>>,RingMatrix<T extends Ring<T>>,CooRingVector<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 matrix to an equivalent tensor with the specified shape.
      Specified by:
      toTensor in class AbstractCooRingMatrix<CooRingMatrix<T extends Ring<T>>,RingMatrix<T extends Ring<T>>,CooRingVector<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
    • makeLikeTensor

      public CooRingMatrix<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<CooRingMatrix<T extends Ring<T>>,RingMatrix<T extends Ring<T>>,T extends Ring<T>[],T extends Ring<T>>
      Specified by:
      makeLikeTensor in class AbstractTensor<CooRingMatrix<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.
    • tensorDot

      public RingTensor<T> tensorDot(CooRingMatrix<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.
      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.
    • mult

      public RingVector<T> mult(CooRingVector<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.
    • toCsr

      public CsrRingMatrix<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 AbstractCooRingMatrix<CooRingMatrix<T extends Ring<T>>,RingMatrix<T extends Ring<T>>,CooRingVector<T extends Ring<T>>,T extends Ring<T>>
      Returns:
      A CSR matrix equivalent to this COO matrix.
    • 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.
    • abs

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

      public CooRingMatrix<T> div(CooRingMatrix<T> b)
      Computes the element-wise quotient of two matrices.

      Warning: This method will throw a UnsupportedOperationException as division is not supported for ring tensors.

      Parameters:
      b - Second matrix in the element-wise quotient.
      Returns:
      The element-wise quotient of this matrix and b.