Class RingMatrix<T extends Ring<T>>

java.lang.Object
org.flag4j.arrays.backend.AbstractTensor<RingMatrix<T>,T[],T>
org.flag4j.arrays.backend.semiring_arrays.AbstractDenseSemiringTensor<RingMatrix<T>,T>
org.flag4j.arrays.backend.semiring_arrays.AbstractDenseSemiringMatrix<RingMatrix<T>,RingVector<T>,T>
org.flag4j.arrays.backend.ring_arrays.AbstractDenseRingMatrix<RingMatrix<T>,RingVector<T>,T>
org.flag4j.arrays.dense.RingMatrix<T>
Type Parameters:
T - Type of the ring element for the matrix.
All Implemented Interfaces:
Serializable, MatrixMixin<RingMatrix<T>,RingMatrix<T>,RingVector<T>,T>, RingTensorMixin<RingMatrix<T>,RingMatrix<T>,T>, TensorOverRing<RingMatrix<T>,RingMatrix<T>,T[],T>, SemiringTensorMixin<RingMatrix<T>,RingMatrix<T>,T>, TensorOverSemiring<RingMatrix<T>,RingMatrix<T>,T[],T>
public class RingMatrix<T extends Ring<T>> extends AbstractDenseRingMatrix<RingMatrix<T>,RingVector<T>,T>

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

A RingMatrix 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 unitary, real, or complex.

Example Usage:

Using 32-bit real integers: 


 // Constructing an integer matrix from a 2D array.
 RealInt32[][] data = {
     { new RealInt32(5), new RealInt32(-3) },
     { new RealInt32(-7), new RealInt32(8) }
 };
 RingMatrix<RealInt32> matrix = new FieldMatrix(data);

 // Performing matrix multiplication.
 RingMatrix<RealInt32> result = matrix.mult(matrix);

 // Performing matrix transpose.
 RingMatrix<RealInt32> transpose = matrix.T();

Using 128-bit complex number: 


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

 // Performing matrix multiplication.
 RingMatrix<Complex128> result = matrix.mult(matrix);

 // Performing matrix transpose.
 RingMatrix<Complex128> transpose = matrix.T();
See Also:

  • Constructor Details

    • RingMatrix

      public RingMatrix(Shape shape, T[] entries)
      Creates a tensor with the specified data and shape.
      Parameters:
      shape - Shape of this tensor.
      entries - Entries of this tensor. If this tensor is dense, this specifies all data within the tensor. If this tensor is sparse, this specifies only the non-zero data of the tensor.

    • RingMatrix

      public RingMatrix(int rows, int cos, T[] entries)
      Creates a dense ring 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.

    • RingMatrix

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

    • RingMatrix

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

    • RingMatrix

      public RingMatrix(int rows, int cols, T[][] entries)
      Creates a dense ring 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.

    • RingMatrix

      public RingMatrix(int rows, int cols, T fillValue)
      Creates a dense ring 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

    • makeLikeVector

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

    • makeLikeVector

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

    • makeLikeCooMatrix

      protected CooRingMatrix<T> makeLikeCooMatrix(Shape shape, T[] 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<RingMatrix<T extends Ring<T>>,RingVector<T extends Ring<T>>,T extends Ring<T>>
      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 CsrRingMatrix<T> makeLikeCsrMatrix(Shape shape, T[] 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 AbstractDenseSemiringMatrix<RingMatrix<T extends Ring<T>>,RingVector<T extends Ring<T>>,T extends Ring<T>>
      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.

    • makeLikeCooTensor

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

    • makeLikeTensor

      public RingMatrix<T> makeLikeTensor(Shape shape, T[] 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<RingMatrix<T extends Ring<T>>,RingMatrix<T extends Ring<T>>,T extends Ring<T>[],T extends Ring<T>>
      Specified by:
      makeLikeTensor in class AbstractTensor<RingMatrix<T extends Ring<T>>,T extends Ring<T>[],T extends Ring<T>>
      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.

    • toTensor

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

    • toTensor

      public RingTensor<T> toTensor(Shape newShape)
      Converts this matrix to an equivalent tensor with the specified newShape.
      Specified by:
      toTensor in class AbstractDenseSemiringMatrix<RingMatrix<T extends Ring<T>>,RingVector<T extends Ring<T>>,T extends Ring<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 Ring<T>> RingMatrix<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 Ring<T>> RingMatrix<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 Ring<T>> RingMatrix<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:

    • toCoo

      public CooRingMatrix<T> toCoo(double estimatedSparsity)
      Converts this matrix to an equivalent sparse COO matrix.
      Overrides:
      toCoo in class AbstractDenseSemiringMatrix<RingMatrix<T extends Ring<T>>,RingVector<T extends Ring<T>>,T extends Ring<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 CooRingMatrix<T> toCoo()
      Converts this dense tensor to an equivalent sparse COO tensor.
      Overrides:
      toCoo in class AbstractDenseSemiringMatrix<RingMatrix<T extends Ring<T>>,RingVector<T extends Ring<T>>,T extends Ring<T>>
      Returns:
      A sparse COO tensor equivalent to this dense tensor.
      See Also:

    • toCsr

      public CsrRingMatrix<T> toCsr()
      Converts this matrix to an equivalent sparse CSR matrix.
      Overrides:
      toCsr in class AbstractDenseSemiringMatrix<RingMatrix<T extends Ring<T>>,RingVector<T extends Ring<T>>,T extends Ring<T>>
      Returns:
      A sparse CSR matrix that is equivalent to this dense matrix.
      See Also:

    • toCsr

      public CsrRingMatrix<T> toCsr(double estimatedSparsity)
      Converts this matrix to an equivalent sparse CSR matrix.
      Overrides:
      toCsr in class AbstractDenseSemiringMatrix<RingMatrix<T extends Ring<T>>,RingVector<T extends Ring<T>>,T extends Ring<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:

    • pow

      public RingMatrix<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 #mult(Matrix) 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.

    • sub

      public RingMatrix<T> sub(RingMatrix<T> b)

      Computes the element-wise difference of two matrices.

      This method will throw an UnsupportedOperationException as subtraction is not defined for a general ring.

      Specified by:
      sub in interface MatrixMixin<RingMatrix<T extends Ring<T>>,RingMatrix<T extends Ring<T>>,RingVector<T extends Ring<T>>,T extends Ring<T>>
      Specified by:
      sub in interface TensorOverRing<RingMatrix<T extends Ring<T>>,RingMatrix<T extends Ring<T>>,T extends Ring<T>[],T extends Ring<T>>
      Overrides:
      sub in class AbstractDenseRingMatrix<RingMatrix<T extends Ring<T>>,RingVector<T extends Ring<T>>,T extends Ring<T>>
      Parameters:
      b - Second matrix in the element-wise difference.
      Returns:
      The element-wise difference of this matrix and b.

    • abs

      public Matrix abs()
      Computes the element-wise absolute value of this tensor.
      Returns:
      The element-wise absolute value of this tensor.

    • div

      public RingMatrix<T> div(RingMatrix<T> b)

      Computes the element-wise quotient of two matrices.

      This method will throw an UnsupportedOperationException as division is not defined for a general ring.

      Parameters:
      b - Second matrix in the element-wise quotient.
      Returns:
      The element-wise quotient of this matrix and b.

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