Class SemiringMatrix<T extends Semiring<T>>

java.lang.Object
org.flag4j.arrays.backend.AbstractTensor<SemiringMatrix<T>,T[],T>
org.flag4j.arrays.backend.semiring_arrays.AbstractDenseSemiringTensor<SemiringMatrix<T>,T>
org.flag4j.arrays.backend.semiring_arrays.AbstractDenseSemiringMatrix<SemiringMatrix<T>,SemiringVector<T>,T>
org.flag4j.arrays.dense.SemiringMatrix<T>
Type Parameters:
T - Type of the semiring element for the matrix.
All Implemented Interfaces:
Serializable, MatrixMixin<SemiringMatrix<T>,SemiringMatrix<T>,SemiringVector<T>,T>, SemiringTensorMixin<SemiringMatrix<T>,SemiringMatrix<T>,T>, TensorOverSemiring<SemiringMatrix<T>,SemiringMatrix<T>,T[],T>
public class SemiringMatrix<T extends Semiring<T>> extends AbstractDenseSemiringMatrix<SemiringMatrix<T>,SemiringVector<T>,T>

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

A SemiringMatrix 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 a boolean semiring: 


 // Constructing an integer matrix from a 2D array of booleans
 BoolSemiring[][] data = {
     { new BoolSemiring(true), new BoolSemiring(false) },
     { new BoolSemiring(true), new BoolSemiring(true) }
 };
 SemiringMatrix<BoolSemiring> matrix = new FieldMatrix(data);

 // Add matrices (equivalent to element-wise OR).
 SemiringMatrix<BoolSemiring> sum = matrix.add(matrix);

 // Element-wise product of matrices (equivalent to element-wise AND).
 SemiringMatrix<BoolSemiring> prod = matrix.elemMult(matrix);

 // Performing matrix multiplication.
 SemiringMatrix<BoolSemiring> result = matrix.mult(matrix);

 // Performing matrix transpose.
 SemiringMatrix<BoolSemiring> transpose = matrix.T();

Using 128-bit complex numbers: 


 // 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) }
 };
 SemiringMatrix<Complex128> matrix = new FieldMatrix(complexData);

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

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

  • Constructor Details

    • SemiringMatrix

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

    • SemiringMatrix

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

    • SemiringMatrix

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

    • SemiringMatrix

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

    • SemiringMatrix

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

    • SemiringMatrix

      public SemiringMatrix(int rows, int cols, T fillValue)
      Creates a dense semiring 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 SemiringVector<T> makeLikeVector(Shape shape, T[] entries)
      Constructs a vector of a similar type as this matrix.
      Specified by:
      makeLikeVector in class AbstractDenseSemiringMatrix<SemiringMatrix<T extends Semiring<T>>,SemiringVector<T extends Semiring<T>>,T extends Semiring<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 SemiringVector<T> makeLikeVector(T[] entries)
      Constructs a vector of a similar type as this matrix.
      Specified by:
      makeLikeVector in class AbstractDenseSemiringMatrix<SemiringMatrix<T extends Semiring<T>>,SemiringVector<T extends Semiring<T>>,T extends Semiring<T>>
      Parameters:
      entries - Entries of the vector.
      Returns:
      A vector of a similar type as this matrix.

    • makeLikeCooMatrix

      protected CooSemiringMatrix<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<SemiringMatrix<T extends Semiring<T>>,SemiringVector<T extends Semiring<T>>,T extends Semiring<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 CsrSemiringMatrix<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<SemiringMatrix<T extends Semiring<T>>,SemiringVector<T extends Semiring<T>>,T extends Semiring<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 CooSemiringTensor<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<SemiringMatrix<T extends Semiring<T>>,T extends Semiring<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 SemiringMatrix<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<SemiringMatrix<T extends Semiring<T>>,SemiringMatrix<T extends Semiring<T>>,T extends Semiring<T>[],T extends Semiring<T>>
      Specified by:
      makeLikeTensor in class AbstractTensor<SemiringMatrix<T extends Semiring<T>>,T extends Semiring<T>[],T extends Semiring<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 SemiringTensor<T> toTensor()
      Converts this matrix to an equivalent tensor.
      Specified by:
      toTensor in class AbstractDenseSemiringMatrix<SemiringMatrix<T extends Semiring<T>>,SemiringVector<T extends Semiring<T>>,T extends Semiring<T>>
      Returns:
      A tensor with the same shape and data as this matrix.

    • toTensor

      public SemiringTensor<T> toTensor(Shape newShape)
      Converts this matrix to an equivalent tensor with the specified newShape.
      Specified by:
      toTensor in class AbstractDenseSemiringMatrix<SemiringMatrix<T extends Semiring<T>>,SemiringVector<T extends Semiring<T>>,T extends Semiring<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 Semiring<T>> SemiringMatrix<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 Semiring<T>> SemiringMatrix<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 Semiring<T>> SemiringMatrix<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 CooSemiringMatrix<T> toCoo(double estimatedSparsity)
      Converts this matrix to an equivalent sparse COO matrix.
      Overrides:
      toCoo in class AbstractDenseSemiringMatrix<SemiringMatrix<T extends Semiring<T>>,SemiringVector<T extends Semiring<T>>,T extends Semiring<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 CooSemiringMatrix<T> toCoo()
      Converts this dense tensor to an equivalent sparse COO tensor.
      Overrides:
      toCoo in class AbstractDenseSemiringMatrix<SemiringMatrix<T extends Semiring<T>>,SemiringVector<T extends Semiring<T>>,T extends Semiring<T>>
      Returns:
      A sparse COO tensor equivalent to this dense tensor.
      See Also:

    • toCsr

      public CsrSemiringMatrix<T> toCsr()
      Converts this matrix to an equivalent sparse CSR matrix.
      Overrides:
      toCsr in class AbstractDenseSemiringMatrix<SemiringMatrix<T extends Semiring<T>>,SemiringVector<T extends Semiring<T>>,T extends Semiring<T>>
      Returns:
      A sparse CSR matrix that is equivalent to this dense matrix.
      See Also:

    • toCsr

      public CsrSemiringMatrix<T> toCsr(double estimatedSparsity)
      Converts this matrix to an equivalent sparse CSR matrix.
      Overrides:
      toCsr in class AbstractDenseSemiringMatrix<SemiringMatrix<T extends Semiring<T>>,SemiringVector<T extends Semiring<T>>,T extends Semiring<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 SemiringMatrix<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 SemiringMatrix<T> sub(SemiringMatrix<T> b)

      Computes the element-wise difference of two matrices.

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

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

    • div

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

      Computes the element-wise quotient of two matrices.

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

      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 SemiringMatrix; 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.