Class CMatrix

java.lang.Object
org.flag4j.arrays.backend.AbstractTensor<CMatrix,Complex128[],Complex128>
org.flag4j.arrays.backend.semiring_arrays.AbstractDenseSemiringTensor<CMatrix,Complex128>
org.flag4j.arrays.backend.semiring_arrays.AbstractDenseSemiringMatrix<CMatrix,CVector,Complex128>
org.flag4j.arrays.backend.ring_arrays.AbstractDenseRingMatrix<CMatrix,CVector,Complex128>
org.flag4j.arrays.backend.field_arrays.AbstractDenseFieldMatrix<CMatrix,CVector,Complex128>
org.flag4j.arrays.dense.CMatrix
All Implemented Interfaces:
Serializable, FieldTensorMixin<CMatrix,CMatrix,Complex128>, TensorOverField<CMatrix,CMatrix,Complex128[],Complex128>, MatrixMixin<CMatrix,CMatrix,CVector,Complex128>, RingTensorMixin<CMatrix,CMatrix,Complex128>, TensorOverRing<CMatrix,CMatrix,Complex128[],Complex128>, SemiringTensorMixin<CMatrix,CMatrix,Complex128>, TensorOverSemiring<CMatrix,CMatrix,Complex128[],Complex128>
public class CMatrix extends AbstractDenseFieldMatrix<CMatrix,CVector,Complex128>

Instances of this class represents a complex dense matrix backed by a Complex128 array. The CMatrix class provides functionality for complex matrix operations, supporting mutable data with a fixed shape. This class extends AbstractDenseFieldMatrix and offers additional methods optimized for complex arithmetic and matrix computations.

A CMatrix is essentially equivalent to a rank-2 tensor but includes extended functionality and may offer improved performance for certain operations compared to general rank-n tensors.

Key Features:

  • Construction from various data types such as arrays of Complex128, double, and String.
  • Support for standard matrix operations like addition, subtraction, multiplication, and exponentiation.
  • Conversion methods to other matrix representations, such as COO (Coordinate) and CSR (Compressed Sparse Row) formats.
  • Utility methods for checking properties like being unitary, real, or complex.

Example Usage: 


 // Constructing a complex matrix from a 2D array of complex numbers
 Complex128[][] complexData = {
     { new Complex128(1, 2), new Complex128(3, 4) },
     { new Complex128(5, 6), new Complex128(7, 8) }
 };
 CMatrix matrix = new CMatrix(complexData);

 // Performing matrix multiplication.
 CMatrix result = matrix.mult(matrix);

 // Performing matrix transpose.
 CMatrix transpose = matrix.T();

 // Performing matrix conjugate transpose (i.e. Hermitian transpose).
 CMatrix conjugateTranspose = matrix.H();

 // Checking if the matrix is unitary.
 boolean isUnitary = matrix.isUnitary();
See Also:

  • Constructor Details

    • CMatrix

      public CMatrix(Shape shape, Complex128[] entries)
      Creates a complex matrix with the specified data and shape.
      Parameters:
      shape - Shape of this matrix.
      entries - Entries of this matrix.

    • CMatrix

      public CMatrix(Shape shape, Complex128 fillValue)
      Creates a complex matrix with the specified shape filled with fillValue.
      Parameters:
      shape - Shape of this matrix.
      fillValue - Value to fill this matrix with.

    • CMatrix

      public CMatrix(Shape shape)
      Creates a zero matrix with the specified shape.
      Parameters:
      shape - Shape of this matrix.

    • CMatrix

      public CMatrix(int size)
      Creates a square zero matrix with the specified size.
      Parameters:
      size - Size of the zero matrix to construct. The resulting matrix will have shape (size, size)

    • CMatrix

      public CMatrix(int rows, int cols, Complex128[] entries)
      Creates a complex matrix with the specified data, and shape.
      Parameters:
      rows - The number of rows in this matrix.
      cols - The number of columns in this matrix.
      entries - Entries of this matrix.

    • CMatrix

      public CMatrix(int rows, int cols, Complex128 fillValue)
      Creates a complex matrix with the specified shape and filled with fillValue.
      Parameters:
      rows - The number of rows in this matrix.
      cols - The number of columns in this matrix.
      fillValue - Value to fill this matrix with.

    • CMatrix

      public CMatrix(int rows, int cols)
      Creates a zero matrix with the specified shape.
      Parameters:
      rows - The number of rows in this matrix.
      cols - The number of columns in this matrix.

    • CMatrix

      public CMatrix(Complex128[][] entries)
      Constructs a complex matrix from a 2D array. The matrix will have the same shape as the array.
      Parameters:
      entries - Entries of the matrix. Assumed to be a square array.

    • CMatrix

      public CMatrix(String[][] entries)

      Constructs a complex matrix from a 2D array of strings. Each string must be formatted properly as a complex number that can be parsed by ComplexNumberParser

      The matrix will have the same shape as the array.

      Parameters:
      entries - Entries of the matrix. Assumed to be a square array.

    • CMatrix

      public CMatrix(Shape shape, double[] entries)
      Constructs a complex matrix with specified shape and data.
      Parameters:
      shape - Shape of the matrix to construct.
      entries - Entries of the matrix.

    • CMatrix

      public CMatrix(double[][] aEntriesReal)
      Constructs a complex matrix from a 2D array of double values.
      Parameters:
      aEntriesReal - Entries of the complex matrix to construct. Each value will be wrapped as Complex128's.

    • CMatrix

      public CMatrix(int numRows, int numCols, double fillValue)
      Constructs a matrix with the specified shape filled with fillValue.
      Parameters:
      numRows - The number of rows in the matrix.
      numCols - The number of rows in the matrix.
      fillValue - Value to fill matrix with.

    • CMatrix

      public CMatrix(int size, Complex128 fillValue)
      Creates a square matrix with the specified size filled with fillValue.
      Parameters:
      size - Size of the square matrix to construct.
      fillValue - Value to fill matrix with.

    • CMatrix

      public CMatrix(int size, Double fillValue)
      Creates a square matrix with the specified size filled with fillValue.
      Parameters:
      size - Size of the square matrix to construct.
      fillValue - Value to fill matrix with.

    • CMatrix

      public CMatrix(Shape shape, Double fillValue)
      Creates matrix with the specified shape filled with fillValue.
      Parameters:
      fillValue - Value to fill matrix with.
      size - Size of the square matrix to construct.

    • CMatrix

      public CMatrix(CMatrix mat)
      Constructs a copy of the specified matrix.
      Parameters:
      mat - Matrix to create copy of.

  • Method Details

    • makeLikeVector

      protected CVector makeLikeVector(Shape shape, Complex128[] entries)
      Constructs a vector of a similar type as this matrix.
      Specified by:
      makeLikeVector in class AbstractDenseSemiringMatrix<CMatrix,CVector,Complex128>
      Parameters:
      shape - Shape of the vector to construct. Must be rank 1.
      entries - Entries of the vector.
      Returns:
      A vector of a similar type as this matrix.

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

    • norm

      public double norm()
      // TODO: Update javadoc. Computes the Euclidean norm of this vector.
      Returns:
      The Euclidean norm of this vector.

    • norm

      public double norm(double p)
      // TODO: Update javadoc. Computes the p-norm of this vector.
      Parameters:
      p - p value in the p-norm.
      Returns:
      The Euclidean norm of this vector.

    • norm

      public double norm(double p, double q)
      // TODO: Update javadoc. Computes the p-norm of this vector.
      Parameters:
      p - p value in the p-norm.
      Returns:
      The Euclidean norm of this vector.

    • makeLikeVector

      protected CVector makeLikeVector(Complex128[] entries)
      Constructs a vector of a similar type as this matrix.
      Specified by:
      makeLikeVector in class AbstractDenseSemiringMatrix<CMatrix,CVector,Complex128>
      Parameters:
      entries - Entries of the vector.
      Returns:
      A vector of a similar type as this matrix.

    • makeLikeCooMatrix

      protected CooCMatrix makeLikeCooMatrix(Shape shape, Complex128[] entries, int[] rowIndices, int[] colIndices)
      Constructs a sparse COO matrix which is of a similar type as this dense matrix.
      Specified by:
      makeLikeCooMatrix in class AbstractDenseSemiringMatrix<CMatrix,CVector,Complex128>
      Parameters:
      shape - Shape of the COO matrix.
      entries - Non-zero data of the COO matrix.
      rowIndices - Non-zero row indices of the COO matrix.
      colIndices - Non-zero column indices of the COO matrix.
      Returns:
      A sparse COO matrix which is of a similar type as this dense matrix.

    • makeLikeCsrMatrix

      public CsrCMatrix makeLikeCsrMatrix(Shape shape, Complex128[] entries, int[] rowPointers, int[] colIndices)
      Constructs a sparse CSR matrix which is of a similar type as this dense matrix.
      Specified by:
      makeLikeCsrMatrix in class AbstractDenseFieldMatrix<CMatrix,CVector,Complex128>
      Parameters:
      shape - Shape of the CSR matrix.
      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 sparse CSR matrix which is of a similar type as this dense matrix.

    • toCoo

      public CooCMatrix toCoo()
      Converts this matrix to an equivalent sparse COO matrix.
      Overrides:
      toCoo in class AbstractDenseSemiringMatrix<CMatrix,CVector,Complex128>
      Returns:
      A sparse COO matrix that is equivalent to this dense matrix.
      See Also:

    • toCoo

      public CooCMatrix toCoo(double estimatedSparsity)
      Converts this matrix to an equivalent sparse COO matrix.
      Overrides:
      toCoo in class AbstractDenseSemiringMatrix<CMatrix,CVector,Complex128>
      Parameters:
      estimatedSparsity - Estimated sparsity of the matrix. Must be between 0 and 1 inclusive. If this is an accurate estimation it may provide a slight speedup and can reduce unneeded memory consumption. If memory is a concern, it is better to over-estimate the sparsity. If speed is the concern it is better to under-estimate the sparsity.
      Returns:
      A sparse COO matrix that is equivalent to this dense matrix.
      See Also:

    • toCsr

      public CsrCMatrix toCsr()
      Converts this matrix to an equivalent sparse CSR matrix.
      Overrides:
      toCsr in class AbstractDenseSemiringMatrix<CMatrix,CVector,Complex128>
      Returns:
      A sparse CSR matrix that is equivalent to this dense matrix.
      See Also:

    • toCsr

      public CsrCMatrix toCsr(double estimatedSparsity)
      Converts this matrix to an equivalent sparse CSR matrix.
      Overrides:
      toCsr in class AbstractDenseSemiringMatrix<CMatrix,CVector,Complex128>
      Parameters:
      estimatedSparsity - Estimated sparsity of the matrix. Must be between 0 and 1 inclusive. If this is an accurate estimation it may provide a slight speedup and can reduce unneeded memory consumption. If memory is a concern, it is better to over-estimate the sparsity. If speed is the concern it is better to under-estimate the sparsity.
      Returns:
      A sparse CSR matrix that is equivalent to this dense matrix.
      See Also:

    • makeLikeCooTensor

      protected CooCMatrix makeLikeCooTensor(Shape shape, Complex128[] entries, int[][] indices)
      Constructs a sparse COO tensor which is of a similar type as this dense tensor.
      Specified by:
      makeLikeCooTensor in class AbstractDenseSemiringTensor<CMatrix,Complex128>
      Parameters:
      shape - Shape of the COO tensor.
      entries - Non-zero data of the COO tensor.
      indices -
      Returns:
      A sparse COO tensor which is of a similar type as this dense tensor.

    • makeLikeTensor

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

    • getEmpty

      public static CMatrix getEmpty(int rows, int cols)
      Constructs an empty matrix with the specified number of rows and columns. The data of the resulting matrix will be all be null.
      Parameters:
      rows - The number of rows in the matrix to construct.
      cols - The number of columns in the matrix to construct.
      Returns:
      An empty matrix (i.e. filled with null values) with the specified shape.

    • add

      public CMatrix add(CooCMatrix b)
      Computes the element-wise sum between two tensors of the same shape.
      Parameters:
      b - Second tensor in the element-wise sum.
      Returns:
      The sum of this tensor with b.
      Throws:
      TensorShapeException - If this tensor and b do not have the same shape.

    • add

      public CMatrix add(Matrix b)
      Computes the element-wise sum between two tensors of the same shape.
      Parameters:
      b - Second tensor in the element-wise sum.
      Returns:
      The sum of this tensor with b.
      Throws:
      TensorShapeException - If this tensor and b do not have the same shape.

    • add

      public CMatrix add(CooMatrix b)
      Computes the element-wise sum between two tensors of the same shape.
      Parameters:
      b - Second tensor in the element-wise sum.
      Returns:
      The sum of this tensor with b.
      Throws:
      TensorShapeException - If this tensor and b do not have the same shape.

    • sub

      public CMatrix sub(CooCMatrix b)
      Computes the element-wise difference between two tensors of the same shape.
      Parameters:
      b - Second tensor in the element-wise difference.
      Returns:
      The difference of this tensor with b.
      Throws:
      TensorShapeException - If this tensor and b do not have the same shape.

    • sub

      public CMatrix sub(Matrix b)
      Computes the element-wise difference between two tensors of the same shape.
      Parameters:
      b - Second tensor in the element-wise difference.
      Returns:
      The difference of this tensor with b.
      Throws:
      TensorShapeException - If this tensor and b do not have the same shape.

    • sub

      public CMatrix sub(CooMatrix b)
      Computes the element-wise difference between two tensors of the same shape.
      Parameters:
      b - Second tensor in the element-wise difference.
      Returns:
      The difference of this tensor with b.
      Throws:
      TensorShapeException - If this tensor and b do not have the same shape.

    • elemMult

      public CooCMatrix elemMult(CooCMatrix b)
      Computes the element-wise multiplication of two tensors of the same shape.
      Parameters:
      b - Second tensor in the element-wise product.
      Returns:
      The element-wise product between this tensor and b.
      Throws:
      IllegalArgumentException - If this tensor and b do not have the same shape.

    • elemMult

      public CMatrix elemMult(Matrix b)
      Computes the element-wise multiplication of two tensors of the same shape.
      Parameters:
      b - Second tensor in the element-wise product.
      Returns:
      The element-wise product between this tensor and b.
      Throws:
      IllegalArgumentException - If this tensor and b do not have the same shape.

    • elemMult

      public CooCMatrix elemMult(CooMatrix b)
      Computes the element-wise multiplication of two tensors of the same shape.
      Parameters:
      b - Second tensor in the element-wise product.
      Returns:
      The element-wise product between this tensor and b.
      Throws:
      IllegalArgumentException - If this tensor and b do not have the same shape.

    • div

      public CMatrix div(Matrix b)
      Computes the element-wise quotient between two tensors.
      Parameters:
      b - Second tensor in the element-wise quotient.
      Returns:
      The element-wise quotient of this tensor with b.

    • toTensor

      public CTensor toTensor()
      Converts this matrix to an equivalent tensor.
      Specified by:
      toTensor in class AbstractDenseSemiringMatrix<CMatrix,CVector,Complex128>
      Returns:
      A tensor with the same shape and data as this matrix.

    • toTensor

      public CTensor toTensor(Shape newShape)
      Converts this matrix to an equivalent tensor with the specified newShape.
      Specified by:
      toTensor in class AbstractDenseSemiringMatrix<CMatrix,CVector,Complex128>
      Parameters:
      newShape - Shape of the tensor. Can be any rank but must be broadcastable to the shape of this matrix.
      Returns:
      A tensor with the specified newShape and the same data as this matrix.

    • I

      public static CMatrix I(int size)
      Constructs an identity matrix of the specified size.
      Parameters:
      size - Size of the identity matrix.
      Returns:
      An identity matrix of specified size.
      Throws:
      IllegalArgumentException - If the specified size is less than 1.
      See Also:

    • I

      public static CMatrix I(int numRows, int numCols)
      Constructs an identity-like matrix of the specified shape. That is, a matrix of zeros with ones along the principle diagonal.
      Parameters:
      numRows - Number of rows in the identity-like matrix.
      numCols - Number of columns in the identity-like matrix.
      Returns:
      An identity matrix of specified shape.
      Throws:
      IllegalArgumentException - If the specified number of rows or columns is less than 1.
      See Also:

    • I

      public static CMatrix I(Shape shape)
      Constructs an identity-like matrix of the specified shape. That is, a matrix of zeros with ones along the principle diagonal.
      Parameters:
      shape - Shape of the identity-like matrix.
      Returns:
      An identity matrix of specified size.
      Throws:
      IllegalArgumentException - If the specified shape is not rank 2.
      See Also:

    • diag

      public static CMatrix diag(Complex128... data)
      Constructs a diagonal matrix from an array specifying the diagonal elements of the matrix.
      Parameters:
      data - Diagonal elements of the matrix. All other values will be zero.
      Returns:
      A diagonal matrix whose diagonal elements are equal to data.
      See Also:

    • diag

      public static CMatrix diag(CVector vec)
      Constructs a diagonal matrix from a vector specifying the diagonal elements of the matrix.
      Parameters:
      vec - Diagonal elements of the matrix. All other values will be zero.
      Returns:
      A diagonal matrix whose diagonal elements are equal to the entries of vec.
      See Also:

    • pow

      public CMatrix pow(int n)

      Computes the matrix multiplication of this matrix with itself n times. This matrix must be square.

      For large n values, this method may be significantly more efficient than calling this.mult(this) a total of n times.

      Parameters:
      n - Number of times to multiply this matrix with itself. Must be non-negative.
      Returns:
      If n=0, then the identity
      Throws:
      IllegalArgumentException - If this matrix is not square (i.e. !this.isSquare()).

    • 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 matrix multiplying this matrix with matrix b.
      Throws:
      LinearAlgebraException - If this.numCols != b.numRows.

    • mult

      public CVector mult(Vector b)
      Computes the matrix-vector multiplication between this matrix and a vector.
      Parameters:
      b - Vector in the matrix-vector multiplication.
      Returns:
      The result of matrix multiplying this matrix with vector b.
      Throws:
      LinearAlgebraException - If the number of columns in this matrix do not equal the number of length of the vector 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 matrix multiplying this matrix with matrix b.
      Throws:
      LinearAlgebraException - If this.numCols != b.numRows.

    • mult

      public CMatrix mult(CooMatrix b)
      Computes the matrix multiplication between two matrices.
      Parameters:
      b - Second matrix in the matrix multiplication.
      Returns:
      The result of matrix multiplying this matrix with matrix b.
      Throws:
      LinearAlgebraException - If this.numCols != b.numRows.

    • mult

      public CMatrix mult(CsrCMatrix b)
      Computes the matrix multiplication between two matrices.
      Parameters:
      b - Second matrix in the matrix multiplication.
      Returns:
      The result of matrix multiplying this matrix with matrix b.
      Throws:
      LinearAlgebraException - If this.numCols != b.numRows.

    • mult

      public CMatrix mult(CooCMatrix b)
      Computes the matrix multiplication between two matrices.
      Parameters:
      b - Second matrix in the matrix multiplication.
      Returns:
      The result of matrix multiplying this matrix with matrix b.
      Throws:
      LinearAlgebraException - If the number of columns in this matrix do not equal the number of rows in matrix b.

    • mult

      public CVector mult(CooVector b)
      Computes the matrix-vector multiplication between this matrix and a vector.
      Parameters:
      b - Vector in the matrix-vector multiplication.
      Returns:
      The result of matrix multiplying this matrix with vector b.
      Throws:
      LinearAlgebraException - If the number of columns in this matrix do not equal the number of length of the vector b.

    • mult

      public CVector mult(CooCVector b)
      Computes the matrix-vector multiplication between this matrix and a vector.
      Parameters:
      b - Vector in the matrix-vector multiplication.
      Returns:
      The result of matrix multiplying this matrix with vector b.
      Throws:
      LinearAlgebraException - If the number of columns in this matrix do not equal the number of length of the vector b.

    • toReal

      public Matrix toReal()
      Converts this complex matrix to a real matrix. This conversion is done by taking the real component of each entry and ignoring the imaginary component.
      Returns:
      A real matrix containing the real components of the data of 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.

    • isUnitary

      public boolean isUnitary()
      Checks if this matrix is unitary. That is, if the inverse of this matrix is approximately equal to its conjugate transpose.
      Overrides:
      isUnitary in class AbstractDenseFieldMatrix<CMatrix,CVector,Complex128>
      Returns:
      true if this matrix it is unitary; false otherwise.

    • round

      public CMatrix round()
      Rounds all data in this matrix to the nearest integer. The real and imaginary components will be rounded independently.
      Returns:
      A new matrix containing the data of this matrix rounded to the nearest integer.

    • round

      public CMatrix round(int precision)
      Rounds all data within this matrix to the specified precision. The real and imaginary components will be rounded independently.
      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 CMatrix 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 CMatrix. false otherwise.

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Generates a human-readable string representing this matrix.
      Overrides:
      toString in class Object
      Returns:
      A human-readable string representing this matrix.