Class SmartMatrix

java.lang.Object
org.flag4j.arrays.SmartMatrix
public class SmartMatrix extends Object

The SmartMatrix class provides a unified interface for performing operations on matrices of various types without requiring users to know the specific underlying implementation. It wraps a base matrix type, such as Matrix, CMatrix, FieldMatrix, or SemiringMatrix, and delegates operations to the appropriate concrete implementation. The concrete implementation must implement MatrixMixin.

Features:

The SmartMatrix class supports most basic matrix operations but may be more limited than the base concrete matrix types.

  • Support for element-wise operations such as addition, subtraction, multiplication, and division.
  • Matrix-specific operations, including transpose and conjugate transpose.
  • Compatibility with heterogeneous matrix types, allowing flexible operation dispatch.
  • Support for methods which return a scalar (e.g. tr(Class)).
  • Human-readable string representations and standard equality checks.

Usage:

  • Creating and adding a real dense and complex dense matrix: 
    
 double[][] realData = {{1.0, 2.0}, {3.0, 4.0}};
 SmartMatrix realMatrix = new SmartMatrix(realData);

 Complex128[][] complexData = {
     {new Complex128(1.0, 1.0), new Complex128(2.0, 2.0)},
     {new Complex128(3.0, 3.0), new Complex128(4.0, 4.0)}
 };
 SmartMatrix complexMatrix = new SmartMatrix(complexData);

 // Compute real-complex element-wise sum.
 SmartMatrix result = realMatrix.add(complexMatrix);
  • Creating and multiplying a real dense and complex sparse CSR matrix: 
    
 // Create real dense matrix.
 SmartMatrix realDenseMatrix = new SmartMatrix(new Matrix(...));

 // Create complex sparse CSR matrix.
 SmartMatrix complexCsrMatrix = new SmartMatrix(new CsrCMatrix(...));

 // Compute real-dense complex-csr matrix multiplication.
 SmartMatrix result = realDenseMatrix.mult(complexCsrMatrix);
  • Example of attempting to compute an unsupported operation: 
    
 // Create real dense matrix.
 SmartMatrix realDenseMatrix = new SmartMatrix(new Matrix(...));

 // Create real sparse COO matrix.
 SmartMatrix complexCsrMatrix = new SmartMatrix(new CooMatrix(...));

 // Will throw UnsupportedOperationException as element-wise division
 //   is not supported between dense and sparse matrices.
 SmartMatrix result = realDenseMatrix.div(complexCsrMatrix);
  • Specifying class for methods which return a scalar: 
    
 // Create real dense matrix.
 SmartMatrix realMatrix = new SmartMatrix(new Matrix(...));

 // Class of the expected return type must be provided.
 // If class is incorrect, a ClassCastException will be thrown.
 Double traceReal = realMatrix.tr(Double.class);

 // Create complex dense matrix.
 SmartMatrix complexMatrix = new SmartMatrix(new CMatrix(...));
 Complex128 traceComplex = complexMatrix.tr(Complex128.class);

Notes:

  • Operations between incompatible base matrix types will result in an UnsupportedOperationException.
    • For example: attempting to divide a dense matrix by a sparse matrix or adding a real matrix to a general field matrix.
  • Equality checks (by equals(Object)) are strict and include type comparison as well as shape and numerical equivalence. This means even if a Matrix and CMatrix are numerically equal, the equals(Object) method will return false because they are not the same type.
See Also:

  • Constructor Details

    • SmartMatrix

      public SmartMatrix(MatrixMixin<?,?,?,?> matrix)
      Constructs a SmartMatrix which is backed by the specified matrix.
      Parameters:
      matrix - The backing matrix for this SmartMatrix.

    • SmartMatrix

      public SmartMatrix(double[][] data)
      Constructs a SmartMatrix from a 2D primitive double array. The matrix which backs this SmartMatrix will be an instance of Matrix.
      Parameters:
      data - Array specifying shape and data of this SmartMatrix.

    • SmartMatrix

      public SmartMatrix(Complex128[][] matrix)
      Constructs a SmartMatrix from a 2D Complex128 array. The matrix which backs this SmartMatrix will be an instance of CMatrix.
      Parameters:
      data - Array specifying shape and data of this SmartMatrix.

    • SmartMatrix

      public SmartMatrix(T[][] matrix)
      Constructs a SmartMatrix from a 2D Field array. The matrix which backs this SmartMatrix will be an instance of FieldMatrix.
      Parameters:
      data - Array specifying shape and data of this SmartMatrix.

    • SmartMatrix

      public SmartMatrix(T[][] matrix)
      Constructs a SmartMatrix from a 2D SemiringMatrix array. The matrix which backs this SmartMatrix will be an instance of SemiringMatrix.
      Parameters:
      data - Array specifying shape and data of this SmartMatrix.

  • Method Details

    • getMatrix

      public MatrixMixin<?,?,?,?> getMatrix()
      Gets reference to the matrix which backs this SmartMatrix.
      Returns:
      The matrix which backs this SmartMatrix.

    • add

      public SmartMatrix add(SmartMatrix b)
      Computes the element-wise sum of two matrices.
      Parameters:
      b - The second matrix in the element-wise sum.
      Returns:
      The element-wise sum of this matrix and b.

    • sub

      public SmartMatrix sub(SmartMatrix b)
      Computes the element-wise difference of two matrices.
      Parameters:
      b - The second matrix in the element-wise difference.
      Returns:
      The element-wise difference of this matrix and b.

    • elemMult

      public SmartMatrix elemMult(SmartMatrix b)
      Computes the element-wise product of two matrices.
      Parameters:
      b - The second matrix in the element-wise product.
      Returns:
      The element-wise product of this matrix and b.

    • div

      public SmartMatrix div(SmartMatrix b)
      Computes the element-wise quotient of two matrices.
      Parameters:
      b - The second matrix in the element-wise quotient.
      Returns:
      The element-wise quotient of this matrix and b.

    • mult

      public SmartMatrix mult(SmartMatrix b)
      Computes the matrix multiplication of two matrices.
      Parameters:
      b - The second matrix in the matrix multiplication problem.
      Returns:
      The result of the matrix multiplication of this matrix and b.

    • T

      public SmartMatrix T()
      Computes the transpose of this matrix.
      Returns:
      The transpose of this matrix.

    • H

      public SmartMatrix H()
      Computes the conjugate transpose of this matrix. This may not be supported for all matrix types.
      Returns:
      The conjugate transpose of this matrix.

    • tr

      public <T> T tr(Class<T> type)

      Computes the trace of this matrix. The result is a scalar value whose type is dependent on the underlying backing matrix of this SmartMatrix instance (e.g., Double, Complex128, etc.).

      This method uses a Class object to specify the expected type of the resulting scalar. It ensures type safety by attempting to cast the result to the specified type. If the cast is not valid, a ClassCastException will be thrown at runtime.

      Usage Examples:

      • Real Matrix: 
        
 SmartMatrix realMatrix = new SmartMatrix(new double[][] {
     {1.0, 2.0},
     {3.0, 4.0}});
 Double128 realTrace = realMatrix.tr(Double.class);
 System.out.println("Trace: " + realMatrix);
      • Complex Matrix: 
        
 SmartMatrix complexMatrix = new SmartMatrix(new Complex128[][] {
     {new Complex128(1.0, 1.0), new Complex128(2.0, 2.0)},
     {new Complex128(3.0, 3.0), new Complex128(4.0, 4.0)}});
 Complex128 complexTrace = complexMatrix.tr(Complex128.class);
 System.out.println("Trace: " + complexTrace);
      Type Parameters:
      T - The type of the scalar expected as the result.
      Parameters:
      type - The Class object representing the expected type of the resulting scalar.
      Returns:
      The trace of this matrix as an instance of the specified type T.
      Throws:
      ClassCastException - If the resulting trace cannot be cast to the specified type T.
      UnsupportedOperationException - If the trace computation is not supported by the backing matrix of this SmartMatrix instance.

    • get

      public <T> T get(int rowIdx, int colIdx, Class<T> type)
      Gets the element from this matrix at the specified indices. The result is a scalar value whose type is dependent on the underlying backing matrix of this SmartMatrix instance (e.g., Double, Complex128, etc.).

      This method uses a Class object to specify the expected type of the resulting scalar. It ensures type safety by attempting to cast the result to the specified type. If the cast is not valid, a ClassCastException will be thrown at runtime.

      Parameters:
      rowIdx - Row index of the element to get.
      colIdx - Column index of the element to get.
      type - The Class object representing the expected type of the resulting scalar.
      Returns:
      The element of this matrix at the specified row and column index.
      Throws:
      ClassCastException - If the resulting trace cannot be cast to the specified type T.
      UnsupportedOperationException - If the trace computation is not supported by the backing matrix of this invalid input: '{@code @param <T> The type of the scalar expected as the result.'

    • getShape

      public Shape getShape()
      Gets the shape of this matrix.
      Returns:
      The shape of this matrix.

    • 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 Matrix. false otherwise.

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Converts this matrix to a human-readable string.
      Overrides:
      toString in class Object
      Returns:
      A human-readable string representation of this matrix.