Class FieldMatrix<T extends Field<T>>

java.lang.Object
org.flag4j.arrays.backend.AbstractTensor<FieldMatrix<T>,T[],T>
org.flag4j.arrays.backend.semiring_arrays.AbstractDenseSemiringTensor<FieldMatrix<T>,T>
org.flag4j.arrays.backend.semiring_arrays.AbstractDenseSemiringMatrix<FieldMatrix<T>,FieldVector<T>,T>
org.flag4j.arrays.backend.ring_arrays.AbstractDenseRingMatrix<FieldMatrix<T>,FieldVector<T>,T>
org.flag4j.arrays.backend.field_arrays.AbstractDenseFieldMatrix<FieldMatrix<T>,FieldVector<T>,T>
org.flag4j.arrays.dense.FieldMatrix<T>
Type Parameters:
T - Type of the field for elements of the matrix.
All Implemented Interfaces:
Serializable, FieldTensorMixin<FieldMatrix<T>,FieldMatrix<T>,T>, TensorOverField<FieldMatrix<T>,FieldMatrix<T>,T[],T>, MatrixMixin<FieldMatrix<T>,FieldMatrix<T>,FieldVector<T>,T>, RingTensorMixin<FieldMatrix<T>,FieldMatrix<T>,T>, TensorOverRing<FieldMatrix<T>,FieldMatrix<T>,T[],T>, SemiringTensorMixin<FieldMatrix<T>,FieldMatrix<T>,T>, TensorOverSemiring<FieldMatrix<T>,FieldMatrix<T>,T[],T>
public class FieldMatrix<T extends Field<T>> extends AbstractDenseFieldMatrix<FieldMatrix<T>,FieldVector<T>,T>

Instances of this class represents a dense matrix backed by a Field array. The FieldMatrix class provides functionality for matrix operations whose elements are members of a field, supporting mutable data with a fixed shape.

A FieldMatrix 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:

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

Example Usage: 


 // Constructing a complex matrix from a 2D array of complex numbers (could be any field).
 Complex128[][] complexData = {
     { new Complex128(1, 2), new Complex128(3, 4) },
     { new Complex128(5, 6), new Complex128(7, 8) }
 };
 FieldMatrix<Complex128> matrix = new FieldMatrix(complexData);

 // Performing matrix multiplication with the transpose of the matrix.
 FieldMatrix<Complex128> result = matrix.mult(matrix.T());

 // Performing matrix conjugate transpose (i.e. Hermitian transpose).
 FieldMatrix<Complex128> conjugateTranspose = matrix.H();  // May not be supported for all field types.

 // Checking if the matrix is upper triangular.
 boolean isTriU = matrix.isTriU();
See Also:

  • Constructor Details

    • FieldMatrix

      public FieldMatrix(Shape shape, T[] entries)
      Creates a dense field matrix with the specified data and shape.
      Parameters:
      shape - Shape of this matrix.
      entries - Entries of this matrix.

    • FieldMatrix

      public FieldMatrix(int rows, int cos, T[] entries)
      Creates a dense field matrix with the specified data and shape.
      Parameters:
      rows - Number of rows in the matrix.
      entries - Entries of this matrix.
      cols - Number of columns in the matrix.

    • FieldMatrix

      public FieldMatrix(T[][] entries)
      Creates a dense field matrix with the specified data and shape.
      Parameters:
      entries - Entries of this matrix.
      shape - Shape of this matrix.

    • FieldMatrix

      public FieldMatrix(Shape shape, T fillValue)
      Creates a dense field matrix with the specified data and filled with filledValue.
      Parameters:
      shape - Shape of this matrix.
      fillValue - Entries of this matrix.

    • FieldMatrix

      public FieldMatrix(int rows, int cols, T[][] entries)
      Creates a dense field matrix with the specified data and shape.
      Parameters:
      rows - Number of rows in the matrix.
      cols - Number of columns in the matrix.
      entries - Entries of this matrix.
      shape - Shape of this matrix.

    • FieldMatrix

      public FieldMatrix(int rows, int cols, T fillValue)
      Creates a dense field matrix with the specified data and filled with filledValue.
      Parameters:
      rows - Number of rows in the matrix.
      cols - Number of columns in the matrix.
      fillValue - Entries of this matrix.

  • Method Details

    • makeLikeCooTensor

      protected CooFieldMatrix<T> makeLikeCooTensor(Shape shape, T[] entries, int[][] indices)
      Constructs a sparse COO tensor which is of a similar type as this dense tensor.
      Specified by:
      makeLikeCooTensor in class AbstractDenseSemiringTensor<FieldMatrix<T extends Field<T>>,T extends Field<T>>
      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.

    • makeLikeVector

      protected FieldVector<T> makeLikeVector(Shape shape, T[] entries)
      Constructs a vector of a similar type as this matrix.
      Specified by:
      makeLikeVector in class AbstractDenseSemiringMatrix<FieldMatrix<T extends Field<T>>,FieldVector<T extends Field<T>>,T extends Field<T>>
      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.

    • makeLikeTensor

      public FieldMatrix<T> makeLikeTensor(Shape shape, T[] entries)
      Constructs a tensor of the same type as this tensor with the given the shape and data.
      Specified by:
      makeLikeTensor in interface TensorOverSemiring<FieldMatrix<T extends Field<T>>,FieldMatrix<T extends Field<T>>,T extends Field<T>[],T extends Field<T>>
      Specified by:
      makeLikeTensor in class AbstractTensor<FieldMatrix<T extends Field<T>>,T extends Field<T>[],T extends Field<T>>
      Parameters:
      shape - Shape of the tensor to construct.
      entries - Entries of the tensor to construct.
      Returns:
      A tensor of the same type as this tensor with the given the shape and data.

    • makeLikeVector

      public FieldVector<T> makeLikeVector(T... entries)
      Constructs a vector of similar type to this matrix with the given data.
      Specified by:
      makeLikeVector in class AbstractDenseSemiringMatrix<FieldMatrix<T extends Field<T>>,FieldVector<T extends Field<T>>,T extends Field<T>>
      Parameters:
      entries - Entries of the vector.
      Returns:
      A vector of similar type to this matrix with the given data.

    • makeLikeCsrMatrix

      public CsrFieldMatrix<T> makeLikeCsrMatrix(Shape shape, T[] entries, int[] rowPointers, int[] colIndices)
      Constructs a sparse CSR matrix of similar type to this dense matrix.
      Specified by:
      makeLikeCsrMatrix in class AbstractDenseFieldMatrix<FieldMatrix<T extends Field<T>>,FieldVector<T extends Field<T>>,T extends Field<T>>
      Parameters:
      shape - Shape of the CSR matrix.
      entries - Non-zero data of the CSR matrix.
      rowPointers - Row pointers of the CSR matrix.
      colIndices - Column indices of the non-zero data in the CSR matrix.
      Returns:
      A sparse CSR matrix with the specified shape and non-zero data.

    • makeLikeCooMatrix

      public CooFieldMatrix<T> makeLikeCooMatrix(Shape shape, T[] entries, int[] rowIndices, int[] colIndices)
      Constructs a sparse COO matrix of similar type to this dense matrix.
      Specified by:
      makeLikeCooMatrix in class AbstractDenseSemiringMatrix<FieldMatrix<T extends Field<T>>,FieldVector<T extends Field<T>>,T extends Field<T>>
      Parameters:
      shape - Shape of the COO matrix.
      entries - Non-zero data of the COO matrix.
      rowIndices - Row indices of the non-zero data in the COO matrix.
      colIndices - Column indices of the non-zero data in the COO matrix.
      Returns:
      A sparse COO matrix with the specified shape and non-zero data.

    • toCoo

      public CooFieldMatrix<T> toCoo(double estimatedSparsity)
      Converts this matrix to an equivalent sparse COO matrix.
      Overrides:
      toCoo in class AbstractDenseSemiringMatrix<FieldMatrix<T extends Field<T>>,FieldVector<T extends Field<T>>,T extends Field<T>>
      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:

    • toCoo

      public CooFieldMatrix<T> toCoo()
      Converts this dense tensor to an equivalent sparse COO tensor.
      Overrides:
      toCoo in class AbstractDenseSemiringMatrix<FieldMatrix<T extends Field<T>>,FieldVector<T extends Field<T>>,T extends Field<T>>
      Returns:
      A sparse COO tensor equivalent to this dense tensor.
      See Also:

    • toCsr

      public CsrFieldMatrix<T> toCsr()
      Converts this matrix to an equivalent sparse CSR matrix.
      Overrides:
      toCsr in class AbstractDenseSemiringMatrix<FieldMatrix<T extends Field<T>>,FieldVector<T extends Field<T>>,T extends Field<T>>
      Returns:
      A sparse CSR matrix that is equivalent to this dense matrix.
      See Also:

    • toCsr

      public CsrFieldMatrix<T> toCsr(double estimatedSparsity)
      Converts this matrix to an equivalent sparse CSR matrix.
      Overrides:
      toCsr in class AbstractDenseSemiringMatrix<FieldMatrix<T extends Field<T>>,FieldVector<T extends Field<T>>,T extends Field<T>>
      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:

    • toTensor

      public FieldTensor<T> toTensor()
      Converts this matrix to an equivalent tensor.
      Specified by:
      toTensor in class AbstractDenseSemiringMatrix<FieldMatrix<T extends Field<T>>,FieldVector<T extends Field<T>>,T extends Field<T>>
      Returns:
      A tensor with the same shape and data as this matrix.

    • toTensor

      public FieldTensor<T> toTensor(Shape newShape)
      Converts this matrix to an equivalent tensor with the specified newShape.
      Specified by:
      toTensor in class AbstractDenseSemiringMatrix<FieldMatrix<T extends Field<T>>,FieldVector<T extends Field<T>>,T extends Field<T>>
      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 <T extends Field<T>> FieldMatrix<T> I(int size, T fieldValue)
      Constructs an identity matrix of the specified size.
      Parameters:
      size - Size of the identity matrix.
      fieldValue - Value of field to create identity matrix for.
      Returns:
      An identity matrix of specified size.
      Throws:
      IllegalArgumentException - If the specified size is less than 1.
      See Also:

    • I

      public static <T extends Field<T>> FieldMatrix<T> I(int numRows, int numCols, T fieldValue)
      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.
      fieldValue - Value of field to create identity matrix for.
      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 <T extends Field<T>> FieldMatrix<T> I(Shape shape, T fieldValue)
      Constructs an identity-like matrix of the specified shape. That is, a matrix of zeros with ones along the principle diagonal.
      Parameters:
      shape - The shape of the identity-like matrix to construct.
      fieldValue - Value of field to create identity matrix for.
      Returns:
      An identity matrix of specified shape.
      Throws:
      IllegalArgumentException - If the specified number of rows or columns is less than 1.
      See Also:

    • pow

      public FieldMatrix<T> 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 significantly more efficient than calling

      invalid reference 
      this.mult(this)
      n times.
      Parameters:
      n - Number of times to multiply this matrix with itself. Must be non-negative.
      Returns:
      If n=0, then the identity

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