Class CsrFieldMatrix<T extends Field<T>>

java.lang.Object
org.flag4j.arrays.backend.AbstractTensor<CsrFieldMatrix<T>,T[],T>
org.flag4j.arrays.backend.semiring_arrays.AbstractCsrSemiringMatrix<CsrFieldMatrix<T>,FieldMatrix<T>,CooFieldVector<T>,T>
org.flag4j.arrays.backend.ring_arrays.AbstractCsrRingMatrix<CsrFieldMatrix<T>,FieldMatrix<T>,CooFieldVector<T>,T>
org.flag4j.arrays.backend.field_arrays.AbstractCsrFieldMatrix<CsrFieldMatrix<T>,FieldMatrix<T>,CooFieldVector<T>,T>
org.flag4j.arrays.sparse.CsrFieldMatrix<T>
Type Parameters:
T - The type of elements stored in this matrix, constrained by the Field interface.
All Implemented Interfaces:
Serializable, FieldTensorMixin<CsrFieldMatrix<T>,FieldMatrix<T>,T>, TensorOverField<CsrFieldMatrix<T>,FieldMatrix<T>,T[],T>, MatrixMixin<CsrFieldMatrix<T>,FieldMatrix<T>,CooFieldVector<T>,T>, RingTensorMixin<CsrFieldMatrix<T>,FieldMatrix<T>,T>, TensorOverRing<CsrFieldMatrix<T>,FieldMatrix<T>,T[],T>, SemiringTensorMixin<CsrFieldMatrix<T>,FieldMatrix<T>,T>, TensorOverSemiring<CsrFieldMatrix<T>,FieldMatrix<T>,T[],T>
public class CsrFieldMatrix<T extends Field<T>> extends AbstractCsrFieldMatrix<CsrFieldMatrix<T>,FieldMatrix<T>,CooFieldVector<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 Field 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);
 Complex128[] data = {
      new Complex128(1, 2), new Complex128(3, 4),
      new Complex128(5, 6), new Complex128(7, 8)
 };
 int[] rowPointers = {0, 1, 1, 1, 1, 3, 3, 3, 4}
 int[] colIndices = {0, 0, 5, 2};

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

 // Add matrices.
 CsrFieldMatrix<Complex128> sum = matrix.add(matrix);

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

 // Compute matrix-vector multiplication.
 FieldVector<Complex128> denseVector = new FieldVector(matrix.numCols, new Complex128(5, 6));
 FieldMatrix<Complex128> matrixVectorProd = matrix.mult(denseVector);
See Also:

  • Constructor Details

    • CsrFieldMatrix

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

    • CsrFieldMatrix

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

    • CsrFieldMatrix

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

  • Method Details

    • unsafeMake

      public static <T extends Field<T>> CsrFieldMatrix<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 CsrFieldMatrix<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<CsrFieldMatrix<T extends Field<T>>,FieldMatrix<T extends Field<T>>,CooFieldVector<T extends Field<T>>,T extends Field<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 CsrFieldMatrix<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<CsrFieldMatrix<T extends Field<T>>,FieldMatrix<T extends Field<T>>,CooFieldVector<T extends Field<T>>,T extends Field<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 FieldMatrix<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<CsrFieldMatrix<T extends Field<T>>,FieldMatrix<T extends Field<T>>,CooFieldVector<T extends Field<T>>,T extends Field<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 CooFieldMatrix<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<CsrFieldMatrix<T extends Field<T>>,FieldMatrix<T extends Field<T>>,CooFieldVector<T extends Field<T>>,T extends Field<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.

    • makeLikeTensor

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

    • toCoo

      public CooFieldMatrix<T> toCoo()
      Converts this sparse CSR matrix to an equivalent sparse COO matrix.
      Specified by:
      toCoo in class AbstractCsrSemiringMatrix<CsrFieldMatrix<T extends Field<T>>,FieldMatrix<T extends Field<T>>,CooFieldVector<T extends Field<T>>,T extends Field<T>>
      Returns:
      A sparse COO matrix equivalent to this sparse CSR matrix.

    • toTensor

      public CooFieldTensor<T> toTensor()
      Converts this CSR matrix to an equivalent sparse COO tensor.
      Specified by:
      toTensor in class AbstractCsrSemiringMatrix<CsrFieldMatrix<T extends Field<T>>,FieldMatrix<T extends Field<T>>,CooFieldVector<T extends Field<T>>,T extends Field<T>>
      Returns:
      An sparse COO tensor equivalent to this CSR matrix.

    • toTensor

      public CooFieldTensor<T> toTensor(Shape shape)
      Converts this CSR matrix to an equivalent COO tensor with the specified shape.
      Overrides:
      toTensor in class AbstractCsrSemiringMatrix<CsrFieldMatrix<T extends Field<T>>,FieldMatrix<T extends Field<T>>,CooFieldVector<T extends Field<T>>,T extends Field<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

    • 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 CooMatrix. False otherwise.

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

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

    • toVector

      public CooFieldVector<T> toVector()
      Converts this matrix to an equivalent vector. If this matrix is not shaped as a row/column vector, it will first be flattened then converted to a vector.
      Specified by:
      toVector in interface MatrixMixin<CsrFieldMatrix<T extends Field<T>>,FieldMatrix<T extends Field<T>>,CooFieldVector<T extends Field<T>>,T extends Field<T>>
      Overrides:
      toVector in class AbstractCsrSemiringMatrix<CsrFieldMatrix<T extends Field<T>>,FieldMatrix<T extends Field<T>>,CooFieldVector<T extends Field<T>>,T extends Field<T>>
      Returns:
      A vector equivalent to this matrix.

    • getRow

      public CooFieldVector<T> getRow(int rowIdx)
      Get the row of this matrix at the specified index.
      Parameters:
      rowIdx - Index of row to get.
      Returns:
      The specified row of this matrix.
      Throws:
      ArrayIndexOutOfBoundsException - If rowIdx is less than zero or greater than/equal to the number of rows in this matrix.

    • getRow

      public CooFieldVector<T> getRow(int rowIdx, int colStart, int colEnd)
      Gets a specified row of this matrix between colStart (inclusive) and colEnd (exclusive).
      Parameters:
      rowIdx - Index of the row of this matrix to get.
      colStart - Starting column of the row (inclusive).
      colEnd - Ending column of the row (exclusive).
      Returns:
      The row at index rowIdx of this matrix between the colStart and colEnd indices.
      Throws:
      IndexOutOfBoundsException - If either colEnd are colStart out of bounds for the shape of this matrix.
      IllegalArgumentException - If colEnd is less than colStart.

    • getCol

      public CooFieldVector<T> getCol(int colIdx)
      Get the column of this matrix at the specified index.
      Parameters:
      colIdx - Index of column to get.
      Returns:
      The specified column of this matrix.
      Throws:
      ArrayIndexOutOfBoundsException - If colIdx is less than zero or greater than/equal to the number of columns in this matrix.

    • getCol

      public CooFieldVector<T> getCol(int colIdx, int rowStart, int rowEnd)
      Gets a specified column of this matrix between rowStart (inclusive) and rowEnd (exclusive).
      Parameters:
      colIdx - Index of the column of this matrix to get.
      rowStart - Starting row of the column (inclusive).
      rowEnd - Ending row of the column (exclusive).
      Returns:
      The column at index colIdx of this matrix between the rowStart and rowEnd indices.
      Throws:
      IllegalArgumentException - If rowEnd is less than rowStart.

    • getDiag

      public CooFieldVector<T> getDiag()
      Extracts the diagonal elements of this matrix and returns them as a vector.
      Returns:
      A vector containing the diagonal data of this matrix.

    • getDiag

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

    • tensorDot

      public AbstractTensor<?,T[],T> tensorDot(CsrFieldMatrix<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.

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

    • dropZeros

      public CsrFieldMatrix<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.