Class CsrSemiringMatrix<T extends Semiring<T>>

java.lang.Object
org.flag4j.arrays.backend.AbstractTensor<CsrSemiringMatrix<T>,T[],T>
org.flag4j.arrays.backend.semiring_arrays.AbstractCsrSemiringMatrix<CsrSemiringMatrix<T>,SemiringMatrix<T>,CooSemiringVector<T>,T>
org.flag4j.arrays.sparse.CsrSemiringMatrix<T>
Type Parameters:
T - The type of elements stored in this matrix, constrained by the Semiring interface.
All Implemented Interfaces:
Serializable, MatrixMixin<CsrSemiringMatrix<T>,SemiringMatrix<T>,CooSemiringVector<T>,T>, SemiringTensorMixin<CsrSemiringMatrix<T>,SemiringMatrix<T>,T>, TensorOverSemiring<CsrSemiringMatrix<T>,SemiringMatrix<T>,T[],T>
public class CsrSemiringMatrix<T extends Semiring<T>> extends AbstractCsrSemiringMatrix<CsrSemiringMatrix<T>,SemiringMatrix<T>,CooSemiringVector<T>,T>

Instances of this class represent a sparse matrix using the compressed sparse row (CSR) format where all data elements belonging to a specified Semiring type. This class is optimized for efficient storage and operations on matrices with a high proportion of zero elements. The non-zero values of the matrix are stored in a compact form, reducing memory usage and improving performance for many matrix operations.

CSR Representation:

A CSR matrix is represented internally using three main arrays:
  • Data: Non-zero values are stored in a one-dimensional array AbstractTensor.data of length AbstractCsrSemiringMatrix.nnz. Any element not specified in data is implicitly zero. It is also possible to explicitly store zero values in this array, although this is generally not desirable. To remove explicitly defined zeros, use dropZeros()
  • Row Pointers: A 1D array AbstractCsrSemiringMatrix.rowPointers of length numRows + 1 where rowPointers[i] indicates the starting index in the data and colIndices arrays for row i. The last entry of rowPointers equals the length of data. That is, all non-zero values in data which are in row i are between data[rowIndices[i] (inclusive) and data[rowIndices[i + 1] (exclusive).
  • Column Indices: A 1D array AbstractCsrSemiringMatrix.colIndices of length AbstractCsrSemiringMatrix.nnz storing the column indices corresponding to each non-zero value in data.

The total number of non-zero elements (AbstractCsrSemiringMatrix.nnz) and the shape are fixed for a given instance, but the values in AbstractTensor.data and their corresponding AbstractCsrSemiringMatrix.rowPointers and AbstractCsrSemiringMatrix.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 row-major sorting of data and indices. If there is any doubt about the ordering of indices, use AbstractCsrSemiringMatrix.sortIndices() to ensure they are explicitly sorted. CSR tensors may also store multiple entries for the same index (referred to as an uncoalesced tensor). To combine all duplicated entries use AbstractCsrSemiringMatrix.coalesce() or AbstractCsrSemiringMatrix.coalesce(BinaryOperator).

CSR matrices are optimized for efficient storage and operations on matrices with a high proportion of zero elements. CSR matrices are ideal for row-wise operations and matrix-vector multiplications. In general, CSR matrices are not efficient at handling many incremental updates. In this case COO matrices are usually preferred.

Conversion to other formats, such as COO or dense matrices, can be performed using toCoo() or AbstractCsrSemiringMatrix.toDense().

Usage Examples:


 // Define matrix data.
 Shape shape = new Shape(8, 8);
 RealFloat32[] data = {
      new RealFloat32(1), new RealFloat32(2),
      new RealFloat32(3), new RealFloat32(4)
 };
 int[] rowPointers = {0, 1, 1, 1, 1, 3, 3, 3, 4}
 int[] colIndices = {0, 0, 5, 2};

 // Create CSR matrix.
 CsrSemiringMatrix<RealFloat32> matrix = new CsrSemiringMatrix<>(shape, data, rowPointers, colIndices);

 // Add matrices.
 CsrSemiringMatrix<RealFloat32> sum = matrix.add(matrix);

 // Compute matrix-matrix multiplication.
 Matrix prod = matrix.mult(matrix);
 CsrSemiringMatrix<RealFloat32> sparseProd = matrix.mult2Csr(matrix);

 // Compute matrix-vector multiplication.
 SemiringVector<RealFloat32> denseVector = new SemiringVector(matrix.numCols, new RealFloat32(5));
 SemiringMatrix<RealFloat32> matrixVectorProd = matrix.mult(denseVector);
See Also:

  • Constructor Details

    • CsrSemiringMatrix

      public CsrSemiringMatrix(Shape shape, T[] data, int[] rowPointers, int[] colIndices)
      Creates a sparse CSR matrix with the specified shape, non-zero data, row pointers, and non-zero column indices.
      Parameters:
      shape - Shape of this tensor.
      data - The non-zero data of this CSR matrix.
      rowPointers - The row pointers for the non-zero values in the sparse CSR matrix.

      rowPointers[i] indicates the starting index within data and colData of all values in row i.

      colIndices - Column indices for each non-zero value in this sparse CSR matrix. Must satisfy data.length == colData.length.

    • CsrSemiringMatrix

      public CsrSemiringMatrix(Shape shape, List<T> data, List<Integer> rowPointers, List<Integer> colIndices)
      Creates a sparse CSR matrix with the specified shape, non-zero data, row pointers, and non-zero column indices.
      Parameters:
      shape - Shape of this tensor.
      data - The non-zero data of this CSR matrix.
      rowPointers - The row pointers for the non-zero values in the sparse CSR matrix.

      rowPointers[i] indicates the starting index within data and colData of all values in row i.

      colIndices - Column indices for each non-zero value in this sparse CSR matrix. Must satisfy data.length == colData.length.

    • CsrSemiringMatrix

      public CsrSemiringMatrix(Shape shape, T semiringElement)
      Constructs a sparse CSR matrix representing the zero matrix for the field which semiringElement belongs to.
      Parameters:
      shape - Shape of the CSR matrix to construct.
      semiringElement - Element of the field which the entries of this matrix belong to.

  • Method Details

    • unsafeMake

      public static <T extends Semiring<T>> CsrSemiringMatrix<T> unsafeMake(Shape shape, Complex128[] data, int[] rowPointers, int[] colIndices)

      Factory to construct a CSR matrix 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:
      shape - The full size of the COO matrix.
      data - The non-zero data of the COO matrix.
      rowPointers - The non-zero row pointers of the COO matrix.
      colIndices - The non-zero column indices of the COO matrix.
      Returns:
      A COO matrix constructed from the provided parameters.

    • makeLikeTensor

      public CsrSemiringMatrix<T> makeLikeTensor(Shape shape, T[] data, int[] rowPointers, int[] colIndices)
      Constructs a sparse CSR tensor of the same type as this tensor with the specified non-zero data and indices.
      Specified by:
      makeLikeTensor in class AbstractCsrSemiringMatrix<CsrSemiringMatrix<T extends Semiring<T>>,SemiringMatrix<T extends Semiring<T>>,CooSemiringVector<T extends Semiring<T>>,T extends Semiring<T>>
      Parameters:
      shape - Shape of the matrix.
      data - Non-zero data of the CSR matrix.
      rowPointers - Row pointers for the non-zero values in the CSR matrix.
      colIndices - Non-zero column indices of the CSR matrix.
      Returns:
      A sparse CSR tensor of the same type as this tensor with the specified non-zero data and indices.

    • makeLikeTensor

      public CsrSemiringMatrix<T> makeLikeTensor(Shape shape, List<T> data, List<Integer> rowPointers, List<Integer> colIndices)
      Constructs a CSR matrix with the specified shape, non-zero data, and non-zero indices.
      Specified by:
      makeLikeTensor in class AbstractCsrSemiringMatrix<CsrSemiringMatrix<T extends Semiring<T>>,SemiringMatrix<T extends Semiring<T>>,CooSemiringVector<T extends Semiring<T>>,T extends Semiring<T>>
      Parameters:
      shape - Shape of the matrix.
      data - Non-zero values of the CSR matrix.
      rowPointers - Row pointers for the non-zero values in the CSR matrix.
      colIndices - Non-zero column indices of the CSR matrix.
      Returns:
      A CSR matrix with the specified shape, non-zero data, and non-zero indices.

    • makeLikeDenseTensor

      public SemiringMatrix<T> makeLikeDenseTensor(Shape shape, T[] data)
      Constructs a dense matrix which is of a similar type to this sparse CSR matrix.
      Specified by:
      makeLikeDenseTensor in class AbstractCsrSemiringMatrix<CsrSemiringMatrix<T extends Semiring<T>>,SemiringMatrix<T extends Semiring<T>>,CooSemiringVector<T extends Semiring<T>>,T extends Semiring<T>>
      Parameters:
      shape - Shape of the dense matrix.
      data - Entries of the dense matrix.
      Returns:
      A dense matrix which is of a similar type to this sparse CSR matrix with the specified shape and data.

    • makeLikeCooMatrix

      public CooSemiringMatrix<T> makeLikeCooMatrix(Shape shape, T[] data, int[] rowIndices, int[] colIndices)

      Constructs a sparse COO matrix of a similar type to this sparse CSR matrix.

      Note: this method constructs a new COO matrix with the specified data and indices. It does not convert this matrix to a CSR matrix. To convert this matrix to a sparse COO matrix use toCoo().

      Specified by:
      makeLikeCooMatrix in class AbstractCsrSemiringMatrix<CsrSemiringMatrix<T extends Semiring<T>>,SemiringMatrix<T extends Semiring<T>>,CooSemiringVector<T extends Semiring<T>>,T extends Semiring<T>>
      Parameters:
      shape - Shape of the COO matrix.
      data - Non-zero data of the COO matrix.
      rowIndices - Non-zero row indices of the sparse COO matrix.
      colIndices - Non-zero column indices of the Sparse COO matrix.
      Returns:
      A sparse COO matrix of a similar type to this sparse CSR matrix.

    • toCoo

      public CooSemiringMatrix<T> toCoo()
      Converts this sparse CSR matrix to an equivalent sparse COO matrix.
      Specified by:
      toCoo in class AbstractCsrSemiringMatrix<CsrSemiringMatrix<T extends Semiring<T>>,SemiringMatrix<T extends Semiring<T>>,CooSemiringVector<T extends Semiring<T>>,T extends Semiring<T>>
      Returns:
      A sparse COO matrix equivalent to this sparse CSR matrix.

    • makeLikeTensor

      public CsrSemiringMatrix<T> makeLikeTensor(Shape shape, T[] data)
      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<CsrSemiringMatrix<T extends Semiring<T>>,SemiringMatrix<T extends Semiring<T>>,T extends Semiring<T>[],T extends Semiring<T>>
      Specified by:
      makeLikeTensor in class AbstractTensor<CsrSemiringMatrix<T extends Semiring<T>>,T extends Semiring<T>[],T extends Semiring<T>>
      Parameters:
      shape - Shape of the tensor to construct.
      data - 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 SemiringTensor<T> tensorDot(CsrSemiringMatrix<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 SemiringVector<T> mult(CooSemiringVector<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.

    • getRow

      public CooSemiringVector<T> getRow(int rowIdx, int colStart, int colEnd)
      Gets a range of a row of this matrix.
      Parameters:
      rowIdx - The index of the row to get.
      colStart - The staring column of the row range to get (inclusive).
      colEnd - The ending column of the row range to get (exclusive).
      Returns:
      A vector containing the elements of the specified row over the range [colStart, colEnd).
      Throws:
      IllegalArgumentException - If rowIdx < 0 || rowIdx >= this.numRows() or colStart < 0 || colStart >= numCols or colEnd < colStart || colEnd > numCols.

    • getCol

      public CooSemiringVector<T> getCol(int colIdx, int rowStart, int rowEnd)
      Gets a range of a column of this matrix.
      Parameters:
      colIdx - The index of the column to get.
      rowStart - The staring row of the column range to get (inclusive).
      rowEnd - The ending row of the column range to get (exclusive).
      Returns:
      A vector containing the elements of the specified column over the range [rowStart, rowEnd).
      Throws:
      IllegalArgumentException - If colIdx < 0 || colIdx >= this.numCols() or rowStart < 0 || rowStart >= numRows or rowEnd < rowStart || rowEnd > numRows.

    • getDiag

      public CooSemiringVector<T> getDiag(int diagOffset)
      Gets the elements of this matrix along the specified diagonal.
      Parameters:
      diagOffset - The diagonal to get within this matrix.
      • If diagOffset == 0: Then the elements of the principle diagonal are collected.
      • If diagOffset < 0: Then the elements of the sub-diagonal diagOffset below the principle diagonal are collected.
      • If diagOffset > 0: Then the elements of the super-diagonal diagOffset above the principle diagonal are collected.
      Returns:
      The elements of the specified diagonal as a vector.

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

    • toTensor

      public CooSemiringTensor<T> toTensor()
      Converts this CSR matrix to an equivalent sparse COO tensor.
      Specified by:
      toTensor in class AbstractCsrSemiringMatrix<CsrSemiringMatrix<T extends Semiring<T>>,SemiringMatrix<T extends Semiring<T>>,CooSemiringVector<T extends Semiring<T>>,T extends Semiring<T>>
      Returns:
      An sparse COO tensor equivalent to this CSR matrix.

    • toTensor

      public CooSemiringTensor<T> toTensor(Shape shape)
      Converts this CSR matrix to an equivalent COO tensor with the specified shape.
      Overrides:
      toTensor in class AbstractCsrSemiringMatrix<CsrSemiringMatrix<T extends Semiring<T>>,SemiringMatrix<T extends Semiring<T>>,CooSemiringVector<T extends Semiring<T>>,T extends Semiring<T>>
      Parameters:
      shape - @return A COO tensor equivalent to this CSR matrix which has been reshaped to newShape
      Returns:
      A COO tensor equivalent to this CSR matrix which has been reshaped to newShape

    • dropZeros

      public CsrSemiringMatrix<T> dropZeros()
      Drops any explicit zeros in this sparse COO matrix.
      Returns:
      A copy of this Csr matrix with any explicitly stored zeros removed.

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