Class CsrCMatrix

java.lang.Object
org.flag4j.arrays.backend.AbstractTensor<CsrCMatrix,Complex128[],Complex128>
org.flag4j.arrays.backend.semiring_arrays.AbstractCsrSemiringMatrix<CsrCMatrix,CMatrix,CooCVector,Complex128>
org.flag4j.arrays.backend.ring_arrays.AbstractCsrRingMatrix<CsrCMatrix,CMatrix,CooCVector,Complex128>
org.flag4j.arrays.backend.field_arrays.AbstractCsrFieldMatrix<CsrCMatrix,CMatrix,CooCVector,Complex128>
org.flag4j.arrays.sparse.CsrCMatrix
All Implemented Interfaces:
Serializable, FieldTensorMixin<CsrCMatrix,CMatrix,Complex128>, TensorOverField<CsrCMatrix,CMatrix,Complex128[],Complex128>, MatrixMixin<CsrCMatrix,CMatrix,CooCVector,Complex128>, RingTensorMixin<CsrCMatrix,CMatrix,Complex128>, TensorOverRing<CsrCMatrix,CMatrix,Complex128[],Complex128>, SemiringTensorMixin<CsrCMatrix,CMatrix,Complex128>, TensorOverSemiring<CsrCMatrix,CMatrix,Complex128[],Complex128>
public class CsrCMatrix extends AbstractCsrFieldMatrix<CsrCMatrix,CMatrix,CooCVector,Complex128>

Instances of this class represent a complex sparse matrix using the compressed sparse row (CSR) format. 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);
 double[] data = {1.0, 2.0, 3.0, 4.0};
 int[] rowPointers = {0, 1, 1, 1, 1, 3, 3, 3, 4}
 int[] colIndices = {0, 0, 5, 2};

 // Create CSR matrix.
 CsrMatrix matrix = new CsrMatrix(shape, data, rowPointers, colIndices);

 // Add matrices.
 CsrMatrix sum = matrix.add(matrix);

 // Compute matrix-matrix multiplication.
 Matrix prod = matrix.mult(matrix);
 CsrMatrix sparseProd = matrix.mult2Csr(matrix);

 // Compute matrix-vector multiplication.
 Vector denseVector = new Vector(matrix.numCols, 5.0);
 Matrix matrixVectorProd = matrix.mult(denseVector);
See Also:

  • Constructor Details

    • CsrCMatrix

      public CsrCMatrix(Shape shape, Complex128[] entries, int[] rowPointers, int[] colIndices)
      Creates a complex sparse CSR matrix with the specified shape, non-zero data, row pointers, and non-zero column indices.
      Parameters:
      shape - Shape of this tensor.
      entries - 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.

    • CsrCMatrix

      public CsrCMatrix(Shape shape, List<Complex128> entries, List<Integer> rowPointers, List<Integer> colIndices)
      Creates a complex sparse CSR matrix with the specified shape, non-zero data, row pointers, and non-zero column indices.
      Parameters:
      shape - Shape of this tensor.
      entries - 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.

    • CsrCMatrix

      public CsrCMatrix(Shape shape)
      Constructs a zero matrix of the specified shape.
      Parameters:
      shape - Shape of the zero matrix.

    • CsrCMatrix

      public CsrCMatrix(int rows, int cols, Complex128[] entries, int[] rowPointers, int[] colIndices)
      Creates a complex sparse CSR matrix with the specified shape, non-zero data, row pointers, and non-zero column indices.
      Parameters:
      rows - The number of rows in the matrix.
      cols - The number of columns in the matrix.
      entries - 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.

    • CsrCMatrix

      public CsrCMatrix(int rows, int cols, List<Complex128> entries, List<Integer> rowPointers, List<Integer> colIndices)
      Creates a complex sparse CSR matrix with the specified shape, non-zero data, row pointers, and non-zero column indices.
      Parameters:
      rows - The number of rows in the matrix.
      cols - The number of columns in the matrix.
      entries - 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.

    • CsrCMatrix

      public CsrCMatrix(int rows, int cols)
      Constructs a zero matrix of the specified shape.
      Parameters:
      rows - The number of rows in the matrix.
      cols - The number of columns in the matrix.

  • Method Details

    • unsafeMake

      public static CsrCMatrix 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.

    • makeEmptyDataArray

      public Complex128[] makeEmptyDataArray(int length)
      Description copied from interface: SemiringTensorMixin
      Creates an empty array of the same type as the data array of this tensor.
      Parameters:
      length - The length of the array to construct.
      Returns:
      An empty array of the same type as the data array of this tensor.

    • makeLikeTensor

      public CsrCMatrix makeLikeTensor(Shape shape, Complex128[] entries, 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<CsrCMatrix,CMatrix,CooCVector,Complex128>
      Parameters:
      shape - Shape of the matrix.
      entries - 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 CsrCMatrix makeLikeTensor(Shape shape, List<Complex128> entries, 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<CsrCMatrix,CMatrix,CooCVector,Complex128>
      Parameters:
      shape - Shape of the matrix.
      entries - 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 CMatrix makeLikeDenseTensor(Shape shape, Complex128[] entries)
      Constructs a dense matrix which is of a similar type to this sparse CSR matrix.
      Specified by:
      makeLikeDenseTensor in class AbstractCsrSemiringMatrix<CsrCMatrix,CMatrix,CooCVector,Complex128>
      Parameters:
      shape - Shape of the dense matrix.
      entries - 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 CooCMatrix makeLikeCooMatrix(Shape shape, Complex128[] entries, 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<CsrCMatrix,CMatrix,CooCVector,Complex128>
      Parameters:
      shape - Shape of the COO matrix.
      entries - 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 CooCMatrix toCoo()
      Converts this sparse CSR matrix to an equivalent sparse COO matrix.
      Specified by:
      toCoo in class AbstractCsrSemiringMatrix<CsrCMatrix,CMatrix,CooCVector,Complex128>
      Returns:
      A sparse COO matrix equivalent to this sparse CSR matrix.

    • toTensor

      public CooCTensor toTensor()
      Converts this CSR matrix to an equivalent sparse COO tensor.
      Specified by:
      toTensor in class AbstractCsrSemiringMatrix<CsrCMatrix,CMatrix,CooCVector,Complex128>
      Returns:
      An sparse COO tensor equivalent to this CSR matrix.

    • toTensor

      public CooCTensor toTensor(Shape shape)
      Converts this CSR matrix to an equivalent COO tensor with the specified shape.
      Overrides:
      toTensor in class AbstractCsrSemiringMatrix<CsrCMatrix,CMatrix,CooCVector,Complex128>
      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

    • toReal

      public CsrMatrix toReal()
      Converts this matrix to an equivalent real matrix. This is done by ignoring the imaginary components of this matrix.
      Returns:
      A real matrix which is equivalent to this matrix.

    • isReal

      public boolean isReal()
      Checks if all data of this matrix are real.
      Returns:
      true if all data of this matrix are real; false otherwise.

    • isComplex

      public boolean isComplex()
      Checks if any entry within this matrix has non-zero imaginary component.
      Returns:
      true if any entry of this matrix has a non-zero imaginary component.

    • makeLikeTensor

      public CsrCMatrix makeLikeTensor(Shape shape, Complex128[] 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<CsrCMatrix,CMatrix,Complex128[],Complex128>
      Specified by:
      makeLikeTensor in class AbstractTensor<CsrCMatrix,Complex128[],Complex128>
      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 CTensor tensorDot(CsrCMatrix 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 CMatrix mult(Matrix b)
      Computes the matrix multiplication between two matrices.
      Parameters:
      b - Second matrix in the matrix multiplication.
      Returns:
      The result of multiplying this matrix with the matrix b.

    • mult

      public CMatrix mult(CMatrix b)
      Computes the matrix multiplication between two matrices.
      Parameters:
      b - Second matrix in the matrix multiplication.
      Returns:
      The result of multiplying this matrix with the matrix b.

    • mult

      public CVector mult(CooCVector 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.

    • mult

      public CMatrix mult(CsrMatrix b)
      Computes the matrix multiplication between two matrices.
      Parameters:
      b - Second matrix in the matrix multiplication.
      Returns:
      The result of multiplying this matrix with the matrix b.

    • mult2Csr

      public CsrCMatrix mult2Csr(CsrMatrix b)
      Computes the matrix multiplication between two matrices.
      Parameters:
      b - Second matrix in the matrix multiplication.
      Returns:
      The result of multiplying this matrix with the matrix b.

    • mult2Csr

      public CsrCMatrix mult2Csr(CsrCMatrix b)
      Computes the matrix multiplication between two matrices.
      Overrides:
      mult2Csr in class AbstractCsrFieldMatrix<CsrCMatrix,CMatrix,CooCVector,Complex128>
      Parameters:
      b - Second matrix in the matrix multiplication.
      Returns:
      The result of multiplying this matrix with the matrix b.
      See Also:

    • getRow

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

    • getCol

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

    • getDiag

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

    • set

      public CsrCMatrix set(double value, int rowIdx, int colIdx)
      Sets the specified index of this matrix to the provided value. This is not done in place as the number of non-zero data in a sparse tensor is fixed.
      Parameters:
      value - Value to set within matrix.
      rowIdx - Row index to set.
      colIdx - Column index to set.
      Returns:
      A new CSR matrix with the specified

    • round

      public CsrCMatrix round(int precision)
      Rounds all data within this matrix to the specified precision.
      Parameters:
      precision - The precision to round to (i.e. the number of decimal places to round to). Must be non-negative.
      Returns:
      A new matrix containing the data of this matrix rounded to the specified precision.

    • roundToZero

      public CsrCMatrix roundToZero(double tolerance)
      Sets all elements of this matrix to zero if they are within tol of zero. This is not done in place.
      Parameters:
      precision - The precision to round to (i.e. the number of decimal places to round to). Must be non-negative.
      Returns:
      A copy of this matrix with all data within tol of zero set to zero.

    • dropZeros

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

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

    • mult

      public CVector mult(CVector 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.

    • mult

      public CVector mult(Vector 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.