Class CooCMatrix

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

A complex sparse matrix stored in coordinate list (COO) format. The AbstractTensor.data of this COO tensor are primitive doubles.

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

COO matrices are well-suited for incremental matrix construction and modification but may not have ideal efficiency for matrix ops like matrix multiplication. For heavy computations, it may be better to construct a matrix as a CooMatrix then convert to a CsrCMatrix (using toCsr()) as CSR (compressed sparse row) matrices are generally better suited for efficient matrix ops.

COO Representation:

A sparse COO matrix is stored as:

Note: many ops assume that the data of the COO 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, call AbstractCooSemiringMatrix.sortIndices().

See Also:

  • Constructor Details

    • CooCMatrix

      public CooCMatrix(Shape shape, Complex128[] 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.

    • CooCMatrix

      public CooCMatrix(Shape shape, List<Complex128> 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.

    • CooCMatrix

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

    • CooCMatrix

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

    • CooCMatrix

      public CooCMatrix(int rows, int cols, List<Complex128> 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 - The number of rows in the matrix.
      cols - The number of columns in the 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.

    • CooCMatrix

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

    • CooCMatrix

      public CooCMatrix(Shape shape, double[] entries, int[] rowIndices, int[] colIndices)
      Creates a sparse coo matrix with the specified non-zero data, non-zero indices, and shape.
      Parameters:
      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.
      rows - The number of rows in the matrix.
      cols - The number of columns in the matrix.

    • CooCMatrix

      public CooCMatrix(int size)
      Constructs a square sparse COO matrix with the specified size filled with zeros.
      Parameters:
      size - Size of the square matrix to construct.

    • CooCMatrix

      public CooCMatrix(int size, Complex128[] entries, int[] rowIndices, int[] colIndices)
      Constructs a square complex sparse COO matrix with the specified size, non-zero values, and non-zero indices.
      Parameters:
      size - Size of the square matrix to construct.
      entries - Non-zero data of the sparse matrix.
      rowIndices - Non-zero row indices of this sparse matrix.
      colIndices - Non-zero column indies of this sparse matrix.

    • CooCMatrix

      public CooCMatrix(CooCMatrix b)
      Constructs a copy of the specified complex sparse COO matrix.
      Parameters:
      b - Matrix to copy.

  • 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 CooCMatrix makeLikeTensor(Shape shape, Complex128[] 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<CooCMatrix,CMatrix,CooCVector,Complex128>
      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 CooCMatrix makeLikeTensor(Shape shape, List<Complex128> 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<CooCMatrix,CMatrix,CooCVector,Complex128>
      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 CooCVector makeLikeVector(Shape shape, Complex128[] entries, int[] indices)
      Constructs a sparse COO vector of a similar type to this COO matrix.
      Specified by:
      makeLikeVector in class AbstractCooSemiringMatrix<CooCMatrix,CMatrix,CooCVector,Complex128>
      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 CMatrix makeLikeDenseTensor(Shape shape, Complex128[] 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<CooCMatrix,CMatrix,CooCVector,Complex128>
      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.

    • makeLikeTensor

      public CooCMatrix 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<CooCMatrix,CMatrix,Complex128[],Complex128>
      Specified by:
      makeLikeTensor in class AbstractTensor<CooCMatrix,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 AbstractTensor<?,Complex128[],Complex128> tensorDot(CooCMatrix 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.

    • makeLikeCsrMatrix

      public CsrCMatrix makeLikeCsrMatrix(Shape shape, Complex128[] entries, int[] rowPointers, int[] colIndices)
      Constructs a sparse CSR matrix of a similar type to this sparse COO matrix.
      Specified by:
      makeLikeCsrMatrix in class AbstractCooFieldMatrix<CooCMatrix,CMatrix,CooCVector,Complex128>
      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.

    • isHermitian

      public boolean isHermitian()
      Checks if a matrix is Hermitian. That is, if the matrix is square and equal to its conjugate transpose.
      Specified by:
      isHermitian in interface MatrixMixin<CooCMatrix,CMatrix,CooCVector,Complex128>
      Overrides:
      isHermitian in class AbstractCooSemiringMatrix<CooCMatrix,CMatrix,CooCVector,Complex128>
      Returns:
      true if this matrix is Hermitian; false otherwise.

    • toCsr

      public CsrCMatrix toCsr()
      Converts this sparse COO matrix to an equivalent sparse CSR matrix.
      Overrides:
      toCsr in class AbstractCooFieldMatrix<CooCMatrix,CMatrix,CooCVector,Complex128>
      Returns:
      A sparse CSR matrix equivalent to this sparse COO matrix.

    • toTensor

      public CooCTensor toTensor()
      Converts this matrix to an equivalent tensor.
      Specified by:
      toTensor in class AbstractCooRingMatrix<CooCMatrix,CMatrix,CooCVector,Complex128>
      Returns:
      A tensor which is equivalent to this matrix.

    • toTensor

      public CooCTensor toTensor(Shape newShape)
      Converts this matrix to an equivalent tensor with the specified shape.
      Specified by:
      toTensor in class AbstractCooRingMatrix<CooCMatrix,CMatrix,CooCVector,Complex128>
      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

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

    • augment

      public CooCMatrix augment(CooVector b)
      Augments a vector to this matrix. That is, inserts the vector as a new column on the right hand side of the matrix.
      Parameters:
      b - The vector to augment to this matrix.
      Returns:
      A new matrix resulting from augmenting the vector b to this matrix.
      Throws:
      IllegalArgumentException - If a.numRows != b.size.

    • augment

      public CooCMatrix augment(CooMatrix a)
      Augments a real COO matrix to this matrix. That is, combines the columns of this matrix and a into a single matrix.
      Parameters:
      a - Matrix to augment to this matrix. Must have the same number of columns as this matrix.
      Returns:
      A matrix resulting from augmenting a to this matrix. Will have shape (this.numRows, this.numCols + a.numCols).
      Throws:
      IllegalArgumentException - If this.numRows != a.numRows

    • toReal

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

    • round

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

    • set

      public CooCMatrix set(double value, int row, int col)
      Sets an index of this matrix to the specified value.
      Parameters:
      value - Value to set.
      row - Row index to set.
      col - Column index to set.
      Returns:
      A reference to this matrix.

    • sub

      public CooCMatrix sub(CooMatrix b)
      Computes the element-wise difference to two matrices.
      Parameters:
      b - The second matrix in the element-wise difference.
      Returns:
      The result of computing the element-wise difference between this matrix and b.

    • elemMult

      public CooCMatrix elemMult(CooMatrix b)
      Computes the element-wise multiplication between this tensor and a real COO matrix.
      Parameters:
      b - Second matrix in the element-wise product.
      Returns:
      The element-wise product of this tensor with b.
      Throws:
      TensorShapeException - If !this.shape.equals(b.shape).

    • elemMult

      public CooCMatrix elemMult(Matrix b)
      Computes the element-wise multiplication between two matrices of the same shape.
      Parameters:
      b - The second matrix in the element-wise product.
      Returns:
      The element-wise product of this tensor with b.

    • elemMult

      public CooCMatrix elemMult(CMatrix b)
      Computes the element-wise multiplication between two matrices of the same shape.
      Parameters:
      b - Second tensor in the element-wise product.
      Returns:
      The element-wise product between this matrix and b.
      Throws:
      TensorShapeException - If !this.shape.equals(b.shape)

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