Class 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>

A complex sparse matrix stored in compressed sparse row (CSR) format. The AbstractTensor.data of this CSR matrix are Complex128's.

The non-zero data and non-zero indices of a CSR matrix are mutable but the AbstractTensor.shape and total number of non-zero data is fixed.

Sparse matrices allow for the efficient storage of and ops on matrices that contain many zero values.

A sparse CSR matrix is stored as:

  • The full shape of the matrix.
  • The non-zero AbstractTensor.data of the matrix. All other data in the matrix are assumed to be zero. Zero values can also explicitly be stored in AbstractTensor.data.
  • The row pointers of the non-zero values in the CSR matrix. Has size numRows + 1
  • rowPointers[i] indicates the starting index within data and colData of all values in row i.

  • The column indices of the non-zero values in the sparse matrix.

Note: many ops assume that the data of the CSR matrix are sorted lexicographically by the row and column indices. (i.e.) by row indices first then column indices. However, this is not explicitly verified. Any ops implemented in this class will preserve the lexicographical sorting.

If indices need to be sorted explicitly, call AbstractCsrSemiringMatrix.sortIndices().

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

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