Interface MatrixMixin<T extends MatrixMixin<T,U,V,W>,U extends MatrixMixin<U,U,?,W>,V extends VectorMixin<V,?,U,W>,W>

Type Parameters:
T - The type of the implementing matrix class.
U - The type of a dense matrix that is analogous to T. If T represents a dense matrix, then T and U should be the same type.
V - The type of vector analogous to T.
W - The type of an individual matrix element, which may be a primitive type, wrapper class, or a custom object.
All Known Implementing Classes:
AbstractCooFieldMatrix, AbstractCooRingMatrix, AbstractCooSemiringMatrix, AbstractCsrFieldMatrix, AbstractCsrRingMatrix, AbstractCsrSemiringMatrix, AbstractDenseFieldMatrix, AbstractDenseRingMatrix, AbstractDenseSemiringMatrix, CMatrix, CooCMatrix, CooFieldMatrix, CooMatrix, CooRingMatrix, CooSemiringMatrix, CsrCMatrix, CsrFieldMatrix, CsrMatrix, CsrRingMatrix, CsrSemiringMatrix, FieldMatrix, Matrix, RingMatrix, SemiringMatrix
public interface MatrixMixin<T extends MatrixMixin<T,U,V,W>,U extends MatrixMixin<U,U,?,W>,V extends VectorMixin<V,?,U,W>,W>

The MatrixMixin interface defines methods that any matrix implementation must support. This interface is designed to ensure a consistent API for various matrix operations, regardless of the underlying matrix type (dense or sparse). It includes methods for accessing matrix properties, performing mathematical operations, and manipulating matrix elements and substructures.

This interface is intended to be used as a mixin for a class which also extends AbstractTensor.

  • Method Summary

    Modifier and Type
    Method
    Description
    <R> R
    accept(MatrixVisitor<R> visitor)
    Accepts a visitor that implements the MatrixVisitor interface.
    T
    add(T b)
    Computes the element-wise sum of two matrices.
    T
    augment(T b)
    Stacks matrices along rows.
    T
    augment(V b)
    Augments a vector to this matrix.
    T
    copy()
    Creates a deep copy of this matrix.
    int
    dataLength()
    Gets the length of the data array which backs this matrix.
    T
    div(T b)
    Computes the element-wise quotient of two matrices.
    T
    elemMult(T b)
    Computes the element-wise product of two matrices.
    default W
    fib(T b)
    Computes the Frobenius inner product of two matrices.
    W
    get(int row, int col)
    Gets the element of this matrix at this specified row and col.
    default V
    getCol(int colIdx)
    Gets the column of this matrix at the specified index.
    V
    getCol(int colIdx, int start, int stop)
    Gets a range of a column of this matrix.
    default V
    getDiag()
    Gets the diagonal elements of this matrix.
    V
    getDiag(int diagOffset)
    Gets the elements of this matrix along the specified diagonal.
    default V
    getRow(int rowIdx)
    Gets the row of this matrix at the specified index.
    V
    getRow(int rowIdx, int start, int stop)
    Gets a range of a row of this matrix.
    Shape
    getShape()
    Gets the shape of this matrix.
    T
    getSlice(int rowStart, int rowEnd, int colStart, int colEnd)
    Gets a specified slice of this matrix.
    default T
    getTriL()
    Extracts the lower-triangular portion of this matrix.
    T
    getTriL(int diagOffset)
    Extracts the lower-triangular portion of this matrix with a specified diagonal offset.
    default T
    getTriU()
    Extracts the upper-triangular portion of this matrix.
    T
    getTriU(int diagOffset)
    Extracts the upper-triangular portion of this matrix with a specified diagonal offset.
    T
    H()
    Computes the Hermitian transpose of this matrix.
    default boolean
    isDiag()
    Checks if this matrix is diagonal.
    boolean
    isHermitian()
    Checks if a matrix is Hermitian.
    boolean
    isI()
    Checks if this matrix is the identity matrix.
    boolean
    isOrthogonal()
    Checks if this matrix is orthogonal.
    default boolean
    isSquare()
    Checks if this matrix is square.
    boolean
    isSymmetric()
    Checks if a matrix is symmetric.
    default boolean
    isTri()
    Checks if this matrix is triangular (i.e. upper triangular, diagonal, lower triangular).
    boolean
    isTriL()
    Checks if this matrix is lower triangular.
    boolean
    isTriU()
    Checks if this matrix is upper triangular.
    default boolean
    isVector()
    Checks if a matrix can be represented as a vector.
    U
    mult(T b)
    Computes the matrix multiplication between two matrices.
    VectorMixin<?,?,?,W>
    mult(V b)
    Computes the matrix-vector multiplication of a vector with this matrix.
    U
    multTranspose(T b)
    Multiplies this matrix with the transpose of the b tensor as if by this.mult(b.T()).
    int
    numCols()
    Gets the number of columns in this matrix.
    int
    numRows()
    Gets the number of rows in this matrix.
    T
    removeCol(int colIndex)
    Removes a specified column from this matrix.
    T
    removeCols(int... colIndices)
    Removes a specified set of columns from this matrix.
    T
    removeRow(int rowIndex)
    Removes a specified row from this matrix.
    T
    removeRows(int... rowIndices)
    Removes a specified set of rows from this matrix.
    T
    set(W value, int row, int col)
    Sets an index of this matrix to the specified value.
    T
    setCol(V col, int colIdx)
    Sets a specified column of this matrix to a vector.
    T
    setRow(V row, int rowIdx)
    Sets a specified row of this matrix to a vector.
    T
    setSliceCopy(T values, int rowStart, int colStart)
    Creates a copy of this matrix and sets a slice of the copy to the specified values.
    T
    stack(T b)
    Stacks matrices along columns.
    default T
    stack(T b, int axis)
    Stacks matrices along specified axis.
    T
    sub(T b)
    Computes the element-wise difference of two matrices.
    T
    swapCols(int colIndex1, int colIndex2)
    Swaps specified columns in the matrix.
    T
    swapRows(int rowIndex1, int rowIndex2)
    Swaps specified rows in the matrix.
    T
    T()
    Computes the transpose of this matrix.
    V
    toVector()
    Converts this matrix to an equivalent vector.
    W
    tr()
    Computes the trace of this matrix.
    default W
    trace()
    Computes the trace of this matrix.
    default int
    vectorType()
    Checks what type of vector this matrix is. i.e. not a vector, a 1x1 matrix, a row vector, or a column vector.

  • Method Details

    • numRows

      int numRows()
      Gets the number of rows in this matrix.
      Returns:
      The number of rows in this matrix.

    • numCols

      int numCols()
      Gets the number of columns in this matrix.
      Returns:
      The number of columns in this matrix.

    • dataLength

      int dataLength()
      Gets the length of the data array which backs this matrix.
      Returns:
      The length of the data array which backs this matrix.

    • get

      W get(int row, int col)
      Gets the element of this matrix at this specified row and col.
      Parameters:
      row - Row index of the item to get from this matrix.
      col - Column index of the item to get from this matrix.
      Returns:
      The element of this matrix at the specified index.

    • getShape

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

    • trace

      default W trace()

      Computes the trace of this matrix. That is, the sum of elements along the principle diagonal of this matrix.

      Same as tr().

      Returns:
      The trace of this matrix.
      Throws:
      IllegalArgumentException - If this matrix is not square.

    • tr

      W tr()

      Computes the trace of this matrix. That is, the sum of elements along the principle diagonal of this matrix.

      Same as trace().

      Returns:
      The trace of this matrix.
      Throws:
      IllegalArgumentException - If this matrix is not square.

    • isSquare

      default boolean isSquare()
      Checks if this matrix is square.
      Returns:
      True if the matrix is square (i.e. the number of rows equals the number of columns). Otherwise, returns false.

    • isVector

      default boolean isVector()
      Checks if a matrix can be represented as a vector. That is, if a matrix has only one row or one column.
      Returns:
      True if this matrix can be represented as either a row or column vector.

    • vectorType

      default int vectorType()
      Checks what type of vector this matrix is. i.e. not a vector, a 1x1 matrix, a row vector, or a column vector.
      Returns:
      An int corresponding to the type of vector this matrix represents:
      • If this matrix can not be represented as a vector, then returns -1.
      • If this matrix is a 1x1 matrix, then returns 0.
      • If this matrix is a row vector, then returns 1.
      • If this matrix is a column vector, then returns 2.

    • isTri

      default boolean isTri()
      Checks if this matrix is triangular (i.e. upper triangular, diagonal, lower triangular).
      Returns:
      true is this matrix is triangular; false otherwise.

    • isDiag

      default boolean isDiag()
      Checks if this matrix is diagonal.
      Returns:
      true is this matrix is diagonal; false otherwise.

    • isTriU

      boolean isTriU()
      Checks if this matrix is upper triangular.
      Returns:
      true is this matrix is upper triangular; false otherwise.
      See Also:

    • isTriL

      boolean isTriL()
      Checks if this matrix is lower triangular.
      Returns:
      true is this matrix is lower triangular; false otherwise.
      See Also:

    • isI

      boolean isI()
      Checks if this matrix is the identity matrix. That is, checks if this matrix is square and contains only ones along the principle diagonal and zeros everywhere else.
      Returns:
      true if this matrix is the identity matrix; false otherwise.

    • mult

      VectorMixin<?,?,?,W> mult(V b)
      Computes the matrix-vector multiplication of a vector with this matrix.
      Parameters:
      b - Vector in the matrix-vector multiplication.
      Returns:
      The result of multiplying this matrix with b.
      Throws:
      LinearAlgebraException - If the number of columns in this matrix do not equal the size of b.

    • mult

      U mult(T 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.

    • multTranspose

      U multTranspose(T b)
      Multiplies this matrix with the transpose of the b tensor as if by this.mult(b.T()). For large matrices, this method may be significantly faster than directly computing the transpose followed by the multiplication as this.mult(b.T()).
      Parameters:
      b - The second matrix in the multiplication and the matrix to transpose.
      Returns:
      The result of multiplying this matrix with the transpose of b.

    • fib

      default W fib(T b)
      Computes the Frobenius inner product of two matrices.
      Parameters:
      b - Second matrix in the Frobenius inner product
      Returns:
      The Frobenius inner product of this matrix and matrix b.
      Throws:
      IllegalArgumentException - If this matrix and b have different shapes.

    • stack

      T stack(T b)
      Stacks matrices along columns.
      Parameters:
      b - Matrix to stack to this matrix.
      Returns:
      The result of stacking this matrix on top of the matrix b.
      Throws:
      IllegalArgumentException - If this matrix and matrix b have a different number of columns.
      See Also:

    • augment

      T augment(T b)
      Stacks matrices along rows.
      Parameters:
      b - Matrix to stack to this matrix.
      Returns:
      The result of stacking b to the right of this matrix.
      Throws:
      IllegalArgumentException - If this matrix and matrix b have a different number of rows.
      See Also:

    • augment

      T augment(V b)
      Augments a vector to this matrix.
      Parameters:
      b - The vector to augment to this matrix.
      Returns:
      The result of augmenting b to this matrix.

    • stack

      default T stack(T b, int axis)
      Stacks matrices along specified axis.
      Also see stack(T) and augment(T).
      Parameters:
      b - Matrix to stack to this matrix.
      axis - Axis along which to stack:
      • If axis=0, then stacks along rows and is equivalent to augment(T).
      • If axis=1, then stacks along columns and is equivalent to stack(T).
      Returns:
      The result of stacking this matrix and b along the specified axis.
      Throws:
      IllegalArgumentException - If this matrix and matrix b have a different length along the corresponding axis.
      IllegalArgumentException - If axis is not either 0 or 1.
      See Also:

    • swapRows

      T swapRows(int rowIndex1, int rowIndex2)
      Swaps specified rows in the matrix. This is done in place.
      Parameters:
      rowIndex1 - Index of the first row to swap.
      rowIndex2 - Index of the second row to swap.
      Returns:
      A reference to this matrix.
      Throws:
      ArrayIndexOutOfBoundsException - If either index is outside the matrix bounds.

    • swapCols

      T swapCols(int colIndex1, int colIndex2)
      Swaps specified columns in the matrix. This is done in place.
      Parameters:
      colIndex1 - Index of the first column to swap.
      colIndex2 - Index of the second column to swap.
      Returns:
      A reference to this matrix.
      Throws:
      ArrayIndexOutOfBoundsException - If either index is outside the matrix bounds.

    • isSymmetric

      boolean isSymmetric()
      Checks if a matrix is symmetric. That is, if the matrix is square and equal to its transpose.
      Returns:
      true if this matrix is symmetric; false otherwise.

    • isHermitian

      boolean isHermitian()
      Checks if a matrix is Hermitian. That is, if the matrix is square and equal to its conjugate transpose.
      Returns:
      true if this matrix is Hermitian; false otherwise.

    • isOrthogonal

      boolean isOrthogonal()
      Checks if this matrix is orthogonal. That is, if the inverse of this matrix is equal to its transpose.
      Returns:
      true if this matrix it is orthogonal; false otherwise.

    • getRow

      default V getRow(int rowIdx)
      Gets the row of this matrix at the specified index.
      Parameters:
      rowIdx - Index of the row to get.
      Returns:
      The row of this matrix at index rowIdx as a vector.
      Throws:
      IllegalArgumentException - If rowIdx < 0 || rowIdx >= this.numRows().

    • getRow

      V getRow(int rowIdx, int start, int stop)
      Gets a range of a row of this matrix.
      Parameters:
      rowIdx - The index of the row to get.
      start - The staring column of the row range to get (inclusive).
      stop - The ending column of the row range to get (exclusive).
      Returns:
      A vector containing the elements of the specified row over the range [start, stop).
      Throws:
      IllegalArgumentException - If rowIdx < 0 || rowIdx >= this.numRows() or start < 0 || start >= numCols or stop < start || stop > numCols.

    • getCol

      default V getCol(int colIdx)
      Gets the column of this matrix at the specified index.
      Parameters:
      colIdx - Index of the column to get.
      Returns:
      The column of this matrix at index colIdx as a vector.
      Throws:
      IllegalArgumentException - If colIdx < 0 || colIdx >= this.numCols().

    • getCol

      V getCol(int colIdx, int start, int stop)
      Gets a range of a column of this matrix.
      Parameters:
      colIdx - The index of the column to get.
      start - The staring row of the column range to get (inclusive).
      stop - The ending row of the column range to get (exclusive).
      Returns:
      A vector containing the elements of the specified column over the range [start, stop).
      Throws:
      IllegalArgumentException - If colIdx < 0 || colIdx >= this.numCols() or start < 0 || start >= numRows or stop < start || stop > numRows.

    • getDiag

      default V getDiag()
      Gets the diagonal elements of this matrix.
      Returns:
      Collects the elements of this matrix along the principle diagonal and returns as a vector. Will have length equal to Math.min(this.numRows(), this.numCols()).

    • getDiag

      V getDiag(int diagOffset)
      Gets the elements of this matrix along the specified diagonal.
      Parameters:
      diagOffset - The diagonal to get within this matrix.
      • If diagOffset == 0: Then the elements of the principle diagonal are collected.
      • If diagOffset < 0: Then the elements of the sub-diagonal diagOffset below the principle diagonal are collected.
      • If diagOffset > 0: Then the elements of the super-diagonal diagOffset above the principle diagonal are collected.
      Returns:
      The elements of the specified diagonal as a vector.

    • setRow

      T setRow(V row, int rowIdx)
      Sets a specified row of this matrix to a vector.
      Parameters:
      row - Vector to replace specified row in this matrix.
      rowIdx - Index of the row to set.
      Returns:
      If this matrix is dense, the row set operation is done in place and a reference to this matrix is returned. If this matrix is sparse a copy will be created with the new row and returned.

    • setCol

      T setCol(V col, int colIdx)
      Sets a specified column of this matrix to a vector.
      Parameters:
      col - Vector to replace specified column in this matrix.
      colIdx - Index of the column to set.
      Returns:
      If this matrix is dense, the column set operation is done in place and a reference to this matrix is returned. If this matrix is sparse a copy will be created with the new column and returned.

    • removeRow

      T removeRow(int rowIndex)
      Removes a specified row from this matrix.
      Parameters:
      rowIndex - Index of the row to remove from this matrix.
      Returns:
      A copy of this matrix with the specified row removed.

    • removeRows

      T removeRows(int... rowIndices)
      Removes a specified set of rows from this matrix.
      Parameters:
      rowIndices - The indices of the rows to remove from this matrix. Assumed to contain unique values.
      Returns:
      A copy of this matrix with the specified column removed.

    • removeCol

      T removeCol(int colIndex)
      Removes a specified column from this matrix.
      Parameters:
      colIndex - Index of the column to remove from this matrix.
      Returns:
      A copy of this matrix with the specified column removed.

    • removeCols

      T removeCols(int... colIndices)
      Removes a specified set of columns from this matrix.
      Parameters:
      colIndices - Indices of the columns to remove from this matrix. Assumed to contain unique values.
      Returns:
      A copy of this matrix with the specified column removed.

    • setSliceCopy

      T setSliceCopy(T values, int rowStart, int colStart)
      Creates a copy of this matrix and sets a slice of the copy to the specified values. The rowStart and colStart parameters specify the upper left index location of the slice to set.
      Parameters:
      values - New values for the specified slice.
      rowStart - Starting row index for the slice (inclusive).
      colStart - Starting column index for the slice (inclusive).
      Returns:
      A copy of this matrix with the given slice set to the specified values.
      Throws:
      IndexOutOfBoundsException - If rowStart or colStart are not within the matrix.
      IllegalArgumentException - If the values slice, with upper left corner at the specified location, does not fit completely within this matrix.

    • getSlice

      T getSlice(int rowStart, int rowEnd, int colStart, int colEnd)
      Gets a specified slice of this matrix.
      Parameters:
      rowStart - Starting row index of slice (inclusive).
      rowEnd - Ending row index of slice (exclusive).
      colStart - Starting column index of slice (inclusive).
      colEnd - Ending row index of slice (exclusive).
      Returns:
      The specified slice of this matrix. This is a completely new matrix and NOT a view into the matrix.
      Throws:
      ArrayIndexOutOfBoundsException - If any of the indices are out of bounds of this matrix.
      IllegalArgumentException - If rowEnd is not greater than rowStart or if colEnd is not greater than colStart.

    • set

      T set(W value, int row, int col)
      Sets an index of this matrix to the specified value.
      Parameters:
      value - Value to set.
      row - Row index to set.
      col - Column index to set.
      Returns:
      A reference to this matrix.

    • getTriU

      T getTriU(int diagOffset)
      Extracts the upper-triangular portion of this matrix with a specified diagonal offset. All other data of the resulting matrix will be zero.
      Parameters:
      diagOffset - Diagonal offset for upper-triangular portion to extract:
      • If zero, then all data at and above the principle diagonal of this matrix are extracted.
      • If positive, then all data at and above the equivalent super-diagonal are extracted.
      • If negative, then all data at and above the equivalent sub-diagonal are extracted.
      Returns:
      The upper-triangular portion of this matrix with a specified diagonal offset. All other data of the returned matrix will be zero.
      Throws:
      IllegalArgumentException - If diagOffset is not in the range (-numRows, numCols).

    • getTriU

      default T getTriU()
      Extracts the upper-triangular portion of this matrix. All other data in the resulting matrix will be zero.
      Returns:
      The upper-triangular portion of this matrix. with all other data in the resulting matrix will be zero.

    • getTriL

      T getTriL(int diagOffset)
      Extracts the lower-triangular portion of this matrix with a specified diagonal offset. All other data of the resulting matrix will be zero.
      Parameters:
      diagOffset - Diagonal offset for lower-triangular portion to extract:
      • If zero, then all data at and above the principle diagonal of this matrix are extracted.
      • If positive, then all data at and above the equivalent super-diagonal are extracted.
      • If negative, then all data at and above the equivalent sub-diagonal are extracted.
      Returns:
      The lower-triangular portion of this matrix with a specified diagonal offset. All other data of the returned matrix will be zero.
      Throws:
      IllegalArgumentException - If diagOffset is not in the range (-numRows, numCols).

    • getTriL

      default T getTriL()
      Extracts the lower-triangular portion of this matrix. All other data in the resulting matrix will be zero.
      Returns:
      The lower-triangular portion of this matrix. with all other data in the resulting matrix will be zero.

    • copy

      T copy()
      Creates a deep copy of this matrix.
      Returns:
      A deep copy of this matrix.

    • H

      T H()
      Computes the Hermitian transpose of this matrix.
      Returns:
      The Hermitian transpose of this matrix.

    • T

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

    • toVector

      V toVector()
      Converts this matrix to an equivalent vector. If this matrix is not a row or column vector it will first be flattened then converted to a vector.
      Returns:
      A vector which

    • accept

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

    • add

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

    • sub

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

    • elemMult

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

    • div

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