Class CooMatrix

java.lang.Object
org.flag4j.arrays.backend.AbstractTensor<CooMatrix,double[],Double>
org.flag4j.arrays.backend.primitive_arrays.AbstractDoubleTensor<CooMatrix>
org.flag4j.arrays.sparse.CooMatrix
All Implemented Interfaces:
Serializable, TensorOverField<CooMatrix,CooMatrix,double[],Double>, MatrixMixin<CooMatrix,Matrix,CooVector,Double>, TensorOverRing<CooMatrix,CooMatrix,double[],Double>, TensorOverSemiring<CooMatrix,CooMatrix,double[],Double>
public class CooMatrix extends AbstractDoubleTensor<CooMatrix> implements MatrixMixin<CooMatrix,Matrix,CooVector,Double>

A real sparse matrix stored in coordinate list (COO) format. The AbstractTensor.data of this COO tensor are primitive doubles.

The non-zero data and non-zero indices of a COO matrix are mutable but the AbstractTensor.shape and total number of non-zero data is fixed.

COO matrices are well-suited for incremental matrix construction and modification but may not have ideal efficiency for matrix ops like matrix multiplication. For heavy computations, it may be better to construct a matrix as a CooMatrix then convert to a CsrMatrix (using toCsr()) as CSR (compressed sparse row) matrices are generally better suited for efficient matrix ops.

COO Representation:

A sparse COO matrix is stored as:

Some ops on sparse tensors behave differently than on dense tensors. For instance, add(double) will not add the scalar to all data of the tensor since this would cause catastrophic loss of sparsity. Instead, such non-zero preserving element-wise ops only act on the non-zero data of the sparse tensor as to not affect the sparsity.

Note: many ops assume that the data of the COO matrix are sorted lexicographically by the row and column indices. (i.e.) by row indices first then column indices. However, this is not explicitly verified. Any ops implemented in this class will preserve the lexicographical sorting.

If indices need to be sorted, call sortIndices().

See Also:

  • Field Details

    • rowIndices

      public final int[] rowIndices
      Row indices for non-zero value of this sparse COO matrix.

    • colIndices

      public final int[] colIndices
      column indices for non-zero value of this sparse COO matrix.

    • nnz

      public final int nnz
      Number of non-zero data in this COO matrix.

    • numRows

      public final int numRows
      The number of rows in this matrix.

    • numCols

      public final int numCols
      The number of columns in this matrix.

  • Constructor Details

    • CooMatrix

      public CooMatrix(Shape shape, double[] data, int[] rowIndices, int[] colIndices)
      Creates a sparse coo matrix with the specified non-zero data, non-zero indices, and shape.
      Parameters:
      shape - Shape of this tensor.
      data - Non-zero data of this sparse matrix.
      rowIndices - Non-zero row indices of this sparse matrix.
      colIndices - Non-zero column indies of this sparse matrix.

    • CooMatrix

      public CooMatrix(int numRows, int numCols, double[] data, int[] rowIndices, int[] colIndices)
      Creates a sparse coo matrix with the specified non-zero data, non-zero indices, and shape.
      Parameters:
      numRows - Number of rows in the matrix.
      numCols - Number of columns in the matrix.
      data - Non-zero data of this sparse matrix.
      rowIndices - Non-zero row indices of this sparse matrix.
      colIndices - Non-zero column indies of this sparse matrix.

    • CooMatrix

      public CooMatrix(Shape shape, List<Double> data, List<Integer> rowIndices, List<Integer> colIndices)
      Creates a sparse coo matrix with the specified non-zero data, non-zero indices, and shape.
      Parameters:
      shape - Shape of this tensor.
      data - Non-zero data of this sparse matrix.
      rowIndices - Non-zero row indices of this sparse matrix.
      colIndices - Non-zero column indies of this sparse matrix.

    • CooMatrix

      public CooMatrix(int size)
      Constructs a square zero matrix with the specified size.
      Parameters:
      size - Size of the square zero matrix to construct.

    • CooMatrix

      public CooMatrix(int rows, int cols)
      Constructs a zero matrix with the specified shape.
      Parameters:
      rows - The number of rows in the zero matrix.
      cols - The number of columns in the zero matrix.

    • CooMatrix

      public CooMatrix(Shape shape)
      Constructs a zero matrix with the specified shape.
      Parameters:
      shape -

    • CooMatrix

      public CooMatrix(int size, double[] data, int[] rowIndices, int[] colIndices)
      Creates a square sparse COO matrix with the specified size, non-zero data, and non-zero indices.
      Parameters:
      size - Size of the square matrix.
      data - Non-zero data of the sparse matrix.
      rowIndices - Row indices of the non-zero data in the matrix.
      colIndices - Column indices of the non-zero data in the matrix.

    • CooMatrix

      public CooMatrix(Shape shape, int[] data, int[] rowIndices, int[] colIndices)
      Creates a sparse coo matrix with the specified non-zero data, non-zero indices, and shape.
      Parameters:
      shape - Shape of this tensor.
      data - Non-zero data of this sparse matrix.
      rowIndices - Non-zero row indices of this sparse matrix.
      colIndices - Non-zero column indies of this sparse matrix.

    • CooMatrix

      public CooMatrix(CooMatrix b)
      Constructs a copy of a real sparse COO matrix.
      Parameters:
      b -

  • Method Details

    • unsafeMake

      public static CooMatrix unsafeMake(Shape shape, double[] data, int[] rowIndices, int[] colIndices)

      Factory to construct a COO matrix which bypasses any validation checks on the data and indices.

      Warning: This method should be used with extreme caution. It primarily exists for internal use. Only use this factory if you are 100% certain the parameters are valid as some methods may throw exceptions or exhibit undefined behavior.

      Parameters:
      shape - The full size of the COO matrix.
      data - The non-zero data of the COO matrix.
      rowIndices - The non-zero row indices of the COO matrix.
      colIndices - The non-zero column indices of the COO matrix.
      Returns:
      A COO matrix constructed from the provided parameters.

    • dataLength

      public int dataLength()
      Gets the length of the data array which backs this matrix.
      Specified by:
      dataLength in interface MatrixMixin<CooMatrix,Matrix,CooVector,Double>
      Overrides:
      dataLength in class AbstractDoubleTensor<CooMatrix>
      Returns:
      The length of the data array which backs this matrix.

    • tensorDot

      public Matrix tensorDot(CooMatrix src2, int[] aAxes, int[] bAxes)
      Computes the tensor contraction of this tensor with a specified tensor over the specified set of axes. That is, computes the sum of products between the two tensors along the specified set of axes.
      Specified by:
      tensorDot in interface TensorOverSemiring<CooMatrix,CooMatrix,double[],Double>
      Parameters:
      src2 - Tensor to contract with this tensor.
      aAxes - Axes along which to compute products for this tensor.
      bAxes - Axes along which to compute products for src2 tensor.
      Returns:
      The tensor dot product over the specified axes.
      Throws:
      IllegalArgumentException - If the two tensors shapes do not match along the specified axes pairwise in aAxes and bAxes.
      IllegalArgumentException - If aAxes and bAxes do not match in length, or if any of the axes are out of bounds for the corresponding tensor.

    • makeLikeTensor

      public CooMatrix makeLikeTensor(Shape shape, double[] data)
      Constructs a sparse COO matrix of the same type as this tensor with the given the shape and data and indices copied from this matrix.
      Specified by:
      makeLikeTensor in interface TensorOverSemiring<CooMatrix,CooMatrix,double[],Double>
      Specified by:
      makeLikeTensor in class AbstractTensor<CooMatrix,double[],Double>
      Parameters:
      shape - Shape of the matrix to construct.
      data - Entries of the matrix to construct.
      Returns:
      A matrix of the same type as this matrix with the given the shape and data.

    • T

      public CooMatrix T(int axis1, int axis2)
      Computes the transpose of a tensor by exchanging axis1 and axis2.
      Specified by:
      T in class AbstractTensor<CooMatrix,double[],Double>
      Parameters:
      axis1 - First axis to exchange.
      axis2 - Second axis to exchange.
      Returns:
      The transpose of this tensor according to the specified axes.
      Throws:
      IndexOutOfBoundsException - If either axis1 or axis2 are out of bounds for the rank of this tensor.
      See Also:

    • T

      public CooMatrix T(int... axes)
      Computes the transpose of this tensor. That is, permutes the axes of this tensor so that it matches the permutation specified by axes.
      Specified by:
      T in class AbstractTensor<CooMatrix,double[],Double>
      Parameters:
      axes - Permutation of tensor axis. If the tensor has rank N, then this must be an array of length N which is a permutation of {0, 1, 2, ..., N-1}.
      Returns:
      The transpose of this tensor with its axes permuted by the axes array.
      Throws:
      IndexOutOfBoundsException - If any element of axes is out of bounds for the rank of this tensor.
      IllegalArgumentException - If axes is not a permutation of {1, 2, 3, ... N-1}.
      See Also:

    • sparsity

      public double sparsity()
      The sparsity of this sparse tensor. That is, the percentage of elements in this tensor which are zero as a decimal.
      Returns:
      The density of this sparse tensor.

    • toDense

      public Matrix toDense()
      Converts this sparse tensor to an equivalent dense tensor.
      Returns:
      A dense tensor equivalent to this sparse tensor.
      Throws:
      ArithmeticException - If the total number of data in this sparse matrix does not fit into an int.

    • toCsr

      public CsrMatrix toCsr()
      Converts this COO matrix to an equivalent CSR matrix.
      Returns:
      A CSR matrix equivalent to this matrix.

    • sortIndices

      public CooMatrix sortIndices()
      Sorts the indices of this tensor in lexicographical order while maintaining the associated value for each index.
      Returns:
      A reference to this matrix.

    • get

      public Double get(int... indices)
      Gets the element of this tensor at the specified indices.
      Specified by:
      get in class AbstractTensor<CooMatrix,double[],Double>
      Parameters:
      indices - Indices of the element to get.
      Returns:
      The element of this tensor at the specified indices.
      Throws:
      ArrayIndexOutOfBoundsException - If any indices are not within this matrix.

    • set

      public CooMatrix set(Double value, int... indices)
      Sets the element of this tensor at the specified indices.
      Specified by:
      set in class AbstractTensor<CooMatrix,double[],Double>
      Parameters:
      value - New value to set the specified index of this tensor to.
      indices - Indices of the element to set.
      Returns:
      A copy of this tensor with the updated value is returned.
      Throws:
      IndexOutOfBoundsException - If indices is not within the bounds of this tensor.

    • flatten

      public CooMatrix flatten()
      Flattens tensor to single dimension while preserving order of data.
      Specified by:
      flatten in class AbstractTensor<CooMatrix,double[],Double>
      Returns:
      The flattened tensor.
      See Also:

    • flatten

      public CooMatrix flatten(int axis)
      Flattens a tensor along the specified axis.
      Specified by:
      flatten in class AbstractTensor<CooMatrix,double[],Double>
      Parameters:
      axis - Axis along which to flatten tensor.
      Throws:
      ArrayIndexOutOfBoundsException - If the axis is not positive or larger than this.{@link #getRank()}-1.
      See Also:

    • reshape

      public CooMatrix reshape(Shape newShape)
      Copies and reshapes this tensor.
      Specified by:
      reshape in class AbstractTensor<CooMatrix,double[],Double>
      Parameters:
      newShape - New shape for the tensor.
      Returns:
      A copy of this tensor with the new shape.
      Throws:
      TensorShapeException - If newShape is not broadcastable to this.shape.

    • add

      public CooMatrix add(CooMatrix b)
      Computes the element-wise sum between two tensors of the same shape.
      Specified by:
      add in interface MatrixMixin<CooMatrix,Matrix,CooVector,Double>
      Specified by:
      add in interface TensorOverSemiring<CooMatrix,CooMatrix,double[],Double>
      Parameters:
      b - Second tensor in the element-wise sum.
      Returns:
      The sum of this tensor with b.
      Throws:
      IllegalArgumentException - If this tensor and b do not have the same shape.

    • sub

      public CooMatrix sub(CooMatrix b)
      Computes the element-wise difference between two tensors of the same shape.
      Specified by:
      sub in interface MatrixMixin<CooMatrix,Matrix,CooVector,Double>
      Specified by:
      sub in interface TensorOverRing<CooMatrix,CooMatrix,double[],Double>
      Parameters:
      b - Second tensor in the element-wise difference.
      Returns:
      The difference of this tensor with b.
      Throws:
      IllegalArgumentException - If this tensor and b do not have the same shape.

    • H

      public CooMatrix H()
      Computes the conjugate transpose of a tensor by exchanging the first and last axes of this tensor and conjugating the exchanged values.
      Specified by:
      H in interface MatrixMixin<CooMatrix,Matrix,CooVector,Double>
      Specified by:
      H in interface TensorOverRing<CooMatrix,CooMatrix,double[],Double>
      Returns:
      The conjugate transpose of this tensor.
      See Also:

    • argmin

      public int[] argmin()
      Finds the indices of the minimum value in this tensor.
      Specified by:
      argmin in interface TensorOverRing<CooMatrix,CooMatrix,double[],Double>
      Returns:
      The indices of the minimum value in this tensor. If this value occurs multiple times, the indices of the first entry (in row-major ordering) are returned.

    • argmax

      public int[] argmax()
      Finds the indices of the maximum value in this tensor.
      Specified by:
      argmax in interface TensorOverRing<CooMatrix,CooMatrix,double[],Double>
      Returns:
      The indices of the maximum value in this tensor. If this value occurs multiple times, the indices of the first entry (in row-major ordering) are returned.

    • argminAbs

      public int[] argminAbs()
      Finds the indices of the minimum absolute value in this tensor.
      Specified by:
      argminAbs in interface TensorOverRing<CooMatrix,CooMatrix,double[],Double>
      Returns:
      The indices of the minimum absolute value in this tensor. If this value occurs multiple times, the indices of the first entry (in row-major ordering) are returned.

    • argmaxAbs

      public int[] argmaxAbs()
      Finds the indices of the maximum absolute value in this tensor.
      Specified by:
      argmaxAbs in interface TensorOverRing<CooMatrix,CooMatrix,double[],Double>
      Returns:
      The indices of the maximum absolute value in this tensor. If this value occurs multiple times, the indices of the first entry (in row-major ordering) are returned.

    • elemMult

      public CooMatrix elemMult(CooMatrix b)
      Computes the element-wise multiplication of two tensors of the same shape.
      Specified by:
      elemMult in interface MatrixMixin<CooMatrix,Matrix,CooVector,Double>
      Specified by:
      elemMult in interface TensorOverSemiring<CooMatrix,CooMatrix,double[],Double>
      Parameters:
      b - Second tensor in the element-wise product.
      Returns:
      The element-wise product between this tensor and b.
      Throws:
      IllegalArgumentException - If this tensor and b do not have the same shape.

    • tensorTr

      public CooMatrix tensorTr(int axis1, int axis2)

      Computes the generalized trace of this tensor along the specified axes.

      Note: for a matrix, the tr() method is preferred.

      The generalized tensor trace is the sum along the diagonal values of the 2D sub-arrays of this tensor specified by axis1 and axis2. The shape of the resulting tensor is equal to this tensor with the axis1 and axis2 removed.

      Specified by:
      tensorTr in interface TensorOverSemiring<CooMatrix,CooMatrix,double[],Double>
      Parameters:
      axis1 - First axis for 2D sub-array.
      axis2 - Second axis for 2D sub-array.
      Returns:
      The generalized trace of this tensor along axis1 and axis2. This will be a tensor of rank this.getRank() - 2 with the same shape as this tensor but with axis1 and axis2 removed.
      Throws:
      IndexOutOfBoundsException - If the two axes are not both larger than zero and less than this tensors rank.
      IllegalArgumentException - If axis1 == axis2 or this.shape.get(axis1) != this.shape.get(axis1) (i.e. the axes are equal or the tensor does not have the same length along the two axes.)

    • prod

      public Double prod()
      Computes the product of all non-zero values in this tensor.
      Specified by:
      prod in interface TensorOverSemiring<CooMatrix,CooMatrix,double[],Double>
      Overrides:
      prod in class AbstractDoubleTensor<CooMatrix>
      Returns:
      The product of all non-zero values in this tensor.

    • T

      public CooMatrix T()
      Computes the transpose of a tensor by exchanging the first and last axes of this tensor.
      Specified by:
      T in interface MatrixMixin<CooMatrix,Matrix,CooVector,Double>
      Overrides:
      T in class AbstractTensor<CooMatrix,double[],Double>
      Returns:
      The transpose of this tensor.
      See Also:

    • recip

      public CooMatrix recip()
      Computes the element-wise reciprocals of non-zero values of this tensor.
      Specified by:
      recip in interface TensorOverField<CooMatrix,CooMatrix,double[],Double>
      Overrides:
      recip in class AbstractDoubleTensor<CooMatrix>
      Returns:
      A tensor containing the reciprocals of the non-zero values of this tensor.

    • add

      public CooMatrix add(double b)
      Adds a scalar value to each non-zero element of this tensor.
      Specified by:
      add in interface TensorOverField<CooMatrix,CooMatrix,double[],Double>
      Overrides:
      add in class AbstractDoubleTensor<CooMatrix>
      Parameters:
      b - Value to add to each non-zero entry of this tensor.
      Returns:
      The result of adding the specified scalar value to each non-zero entry of this tensor.

    • add

      public CooCMatrix add(Complex128 b)
      Adds a scalar value to each non-zero element of this tensor.
      Parameters:
      b - Value to add to each non-zero entry of this tensor.
      Returns:
      The result of adding the specified scalar value to each non-zero entry of this tensor.

    • sub

      public CooMatrix sub(double b)
      Subtracts a scalar value from each non-zero element of this tensor.
      Specified by:
      sub in interface TensorOverField<CooMatrix,CooMatrix,double[],Double>
      Overrides:
      sub in class AbstractDoubleTensor<CooMatrix>
      Parameters:
      b - Value to subtract from each non-zero entry of this tensor.
      Returns:
      The result of subtracting the specified scalar value from each non-zero entry of this tensor.

    • div

      public CooMatrix div(CooMatrix b)

      Computes the element-wise quotient between two tensors.

      Warning: This method is not supported for sparse matrices. If called on a sparse matrix, an UnsupportedOperationException will be thrown. Element-wise division is undefined for sparse matrices as it would almost certainly result in a division by zero.

      Specified by:
      div in interface MatrixMixin<CooMatrix,Matrix,CooVector,Double>
      Specified by:
      div in interface TensorOverField<CooMatrix,CooMatrix,double[],Double>
      Parameters:
      b - Second tensor in the element-wise quotient.
      Returns:
      The element-wise quotient of this tensor with b.

    • sub

      public CooCMatrix sub(Complex128 b)
      Subtracts a scalar value from each non-zero element of this tensor.
      Parameters:
      b - Value to subtract from each non-zero entry of this tensor.
      Returns:
      The result of subtracting the specified scalar value from each non-zero entry of this tensor.

    • numRows

      public int numRows()
      Gets the number of rows in this matrix.
      Specified by:
      numRows in interface MatrixMixin<CooMatrix,Matrix,CooVector,Double>
      Returns:
      The number of rows in this matrix.

    • numCols

      public int numCols()
      Gets the number of columns in this matrix.
      Specified by:
      numCols in interface MatrixMixin<CooMatrix,Matrix,CooVector,Double>
      Returns:
      The number of columns in this matrix.

    • get

      public Double get(int row, int col)
      Gets the element of this matrix at this specified row and col.
      Specified by:
      get in interface MatrixMixin<CooMatrix,Matrix,CooVector,Double>
      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.

    • tr

      public Double tr()

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

      Same as MatrixMixin.trace().

      Specified by:
      tr in interface MatrixMixin<CooMatrix,Matrix,CooVector,Double>
      Returns:
      The trace of this matrix.
      Throws:
      IllegalArgumentException - If this matrix is not square.

    • isTriU

      public boolean isTriU()
      Checks if this matrix is upper triangular.
      Specified by:
      isTriU in interface MatrixMixin<CooMatrix,Matrix,CooVector,Double>
      Returns:
      true is this matrix is upper triangular; false otherwise.
      See Also:

    • isTriL

      public boolean isTriL()
      Checks if this matrix is lower triangular.
      Specified by:
      isTriL in interface MatrixMixin<CooMatrix,Matrix,CooVector,Double>
      Returns:
      true is this matrix is lower triangular; false otherwise.
      See Also:

    • isI

      public 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.
      Specified by:
      isI in interface MatrixMixin<CooMatrix,Matrix,CooVector,Double>
      Returns:
      true if this matrix is the identity matrix; false otherwise.
      See Also:

    • isCloseToI

      public boolean isCloseToI()
      Checks that this matrix is close to the identity matrix.
      Returns:
      True if this matrix is approximately the identity matrix.
      See Also:

    • det

      public Double det()
      Computes the determinant of a square matrix.
      Returns:
      The determinant of this matrix.
      Throws:
      LinearAlgebraException - If this matrix is not square.

    • mult

      public Matrix mult(CooMatrix b)
      Computes the matrix multiplication between two matrices.
      Specified by:
      mult in interface MatrixMixin<CooMatrix,Matrix,CooVector,Double>
      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.

    • mult

      public CMatrix mult(CooCMatrix 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

      public Matrix multTranspose(CooMatrix 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()).
      Specified by:
      multTranspose in interface MatrixMixin<CooMatrix,Matrix,CooVector,Double>
      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

      public Double fib(CooMatrix b)
      Computes the Frobenius inner product of two matrices.
      Specified by:
      fib in interface MatrixMixin<CooMatrix,Matrix,CooVector,Double>
      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

      public CooMatrix stack(CooMatrix b)
      Stacks matrices along columns.
      Specified by:
      stack in interface MatrixMixin<CooMatrix,Matrix,CooVector,Double>
      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

      public CooMatrix augment(CooMatrix b)
      Stacks matrices along rows.
      Specified by:
      augment in interface MatrixMixin<CooMatrix,Matrix,CooVector,Double>
      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

      public CooMatrix augment(CooVector b)
      Augments a vector to this matrix.
      Specified by:
      augment in interface MatrixMixin<CooMatrix,Matrix,CooVector,Double>
      Parameters:
      b - The vector to augment to this matrix.
      Returns:
      The result of augmenting b to this matrix.

    • swapRows

      public CooMatrix swapRows(int rowIndex1, int rowIndex2)
      Swaps specified rows in the matrix. This is done in place.
      Specified by:
      swapRows in interface MatrixMixin<CooMatrix,Matrix,CooVector,Double>
      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

      public CooMatrix swapCols(int colIndex1, int colIndex2)
      Swaps specified columns in the matrix. This is done in place.
      Specified by:
      swapCols in interface MatrixMixin<CooMatrix,Matrix,CooVector,Double>
      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

      public boolean isSymmetric()
      Checks if a matrix is symmetric. That is, if the matrix is square and equal to its transpose.
      Specified by:
      isSymmetric in interface MatrixMixin<CooMatrix,Matrix,CooVector,Double>
      Returns:
      true if this matrix is symmetric; false otherwise.
      See Also:

    • isHermitian

      public boolean isHermitian()
      Checks if a matrix is Hermitian. That is, if the matrix is square and equal to its conjugate transpose.
      Specified by:
      isHermitian in interface MatrixMixin<CooMatrix,Matrix,CooVector,Double>
      Returns:
      true if this matrix is Hermitian; false otherwise.

    • isAntiSymmetric

      public boolean isAntiSymmetric()
      Checks if a matrix is anti-symmetric. That is, if the matrix is equal to the negative of its transpose.
      Returns:
      true if this matrix is anti-symmetric; false otherwise.
      See Also:

    • isOrthogonal

      public boolean isOrthogonal()
      Checks if this matrix is orthogonal. That is, if the inverse of this matrix is equal to its transpose.
      Specified by:
      isOrthogonal in interface MatrixMixin<CooMatrix,Matrix,CooVector,Double>
      Returns:
      true if this matrix it is orthogonal; false otherwise.

    • removeRow

      public CooMatrix removeRow(int rowIndex)
      Removes a specified row from this matrix.
      Specified by:
      removeRow in interface MatrixMixin<CooMatrix,Matrix,CooVector,Double>
      Parameters:
      rowIndex - Index of the row to remove from this matrix.
      Returns:
      A copy of this matrix with the specified row removed.

    • removeRows

      public CooMatrix removeRows(int... rowIndices)
      Removes a specified set of rows from this matrix.
      Specified by:
      removeRows in interface MatrixMixin<CooMatrix,Matrix,CooVector,Double>
      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

      public CooMatrix removeCol(int colIndex)
      Removes a specified column from this matrix.
      Specified by:
      removeCol in interface MatrixMixin<CooMatrix,Matrix,CooVector,Double>
      Parameters:
      colIndex - Index of the column to remove from this matrix.
      Returns:
      a copy of this matrix with the specified column removed.

    • removeCols

      public CooMatrix removeCols(int... colIndices)
      Removes a specified set of columns from this matrix.
      Specified by:
      removeCols in interface MatrixMixin<CooMatrix,Matrix,CooVector,Double>
      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

      public CooMatrix setSliceCopy(CooMatrix 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.
      Specified by:
      setSliceCopy in interface MatrixMixin<CooMatrix,Matrix,CooVector,Double>
      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

      public CooMatrix getSlice(int rowStart, int rowEnd, int colStart, int colEnd)
      Gets a specified slice of this matrix.
      Specified by:
      getSlice in interface MatrixMixin<CooMatrix,Matrix,CooVector,Double>
      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

      public CooMatrix set(Double value, int row, int col)
      Sets an index of this matrix to the specified value.
      Specified by:
      set in interface MatrixMixin<CooMatrix,Matrix,CooVector,Double>
      Parameters:
      value - Value to set.
      row - Row index to set.
      col - Column index to set.
      Returns:
      A reference to this matrix.

    • getTriU

      public CooMatrix 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.
      Specified by:
      getTriU in interface MatrixMixin<CooMatrix,Matrix,CooVector,Double>
      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).

    • getTriL

      public CooMatrix 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.
      Specified by:
      getTriL in interface MatrixMixin<CooMatrix,Matrix,CooVector,Double>
      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).

    • mult

      public Vector mult(CooVector b)
      Computes matrix-vector multiplication.
      Specified by:
      mult in interface MatrixMixin<CooMatrix,Matrix,CooVector,Double>
      Parameters:
      b - Vector in the matrix-vector multiplication.
      Returns:
      The result of matrix multiplying this matrix with vector b.
      Throws:
      IllegalArgumentException - If the number of columns in this matrix do not equal the number of data in the vector b.

    • toVector

      public CooVector toVector()
      Converts this matrix to an equivalent vector. If this matrix is not shaped as a row/column vector, it will first be flattened then converted to a vector.
      Specified by:
      toVector in interface MatrixMixin<CooMatrix,Matrix,CooVector,Double>
      Returns:
      A vector equivalent to this matrix.

    • toTensor

      public CooTensor toTensor()
      Converts this sparse COO matrix to an equivalent sparse COO tensor.
      Returns:
      A sparse COO tensor equivalent to this sparse COO matrix.

    • getRow

      public CooVector getRow(int rowIdx)
      Get the row of this matrix at the specified index.
      Specified by:
      getRow in interface MatrixMixin<CooMatrix,Matrix,CooVector,Double>
      Parameters:
      rowIdx - Index of row to get.
      Returns:
      The specified row of this matrix.
      Throws:
      ArrayIndexOutOfBoundsException - If rowIdx is less than zero or greater than/equal to the number of rows in this matrix.

    • getRow

      public CooVector getRow(int rowIdx, int colStart, int colEnd)
      Gets a specified row of this matrix between colStart (inclusive) and colEnd (exclusive).
      Specified by:
      getRow in interface MatrixMixin<CooMatrix,Matrix,CooVector,Double>
      Parameters:
      rowIdx - Index of the row of this matrix to get.
      colStart - Starting column of the row (inclusive).
      colEnd - Ending column of the row (exclusive).
      Returns:
      The row at index rowIdx of this matrix between the colStart and colEnd indices.
      Throws:
      IndexOutOfBoundsException - If either colEnd are colStart out of bounds for the shape of this matrix.
      IllegalArgumentException - If colEnd is less than colStart.

    • getCol

      public CooVector getCol(int colIdx)
      Get the column of this matrix at the specified index.
      Specified by:
      getCol in interface MatrixMixin<CooMatrix,Matrix,CooVector,Double>
      Parameters:
      colIdx - Index of column to get.
      Returns:
      The specified column of this matrix.
      Throws:
      ArrayIndexOutOfBoundsException - If colIdx is less than zero or greater than/equal to the number of columns in this matrix.

    • getCol

      public CooVector getCol(int colIdx, int rowStart, int rowEnd)
      Gets a specified column of this matrix between rowStart (inclusive) and rowEnd (exclusive).
      Specified by:
      getCol in interface MatrixMixin<CooMatrix,Matrix,CooVector,Double>
      Parameters:
      colIdx - Index of the column of this matrix to get.
      rowStart - Starting row of the column (inclusive).
      rowEnd - Ending row of the column (exclusive).
      Returns:
      The column at index colIdx of this matrix between the rowStart and rowEnd indices.
      Throws:
      IllegalArgumentException - If rowEnd is less than rowStart.

    • getDiag

      public CooVector getDiag()
      Extracts the diagonal elements of this matrix and returns them as a vector.
      Specified by:
      getDiag in interface MatrixMixin<CooMatrix,Matrix,CooVector,Double>
      Returns:
      A vector containing the diagonal data of this matrix.

    • getDiag

      public CooVector getDiag(int diagOffset)
      Gets the elements of this matrix along the specified diagonal.
      Specified by:
      getDiag in interface MatrixMixin<CooMatrix,Matrix,CooVector,Double>
      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.

    • setCol

      public CooMatrix setCol(CooVector values, int colIndex)
      Sets a column of this matrix at the given index to the specified values.
      Specified by:
      setCol in interface MatrixMixin<CooMatrix,Matrix,CooVector,Double>
      Parameters:
      values - New values for the column.
      colIndex - The index of the column which is to be set.
      Returns:
      A copy of this matrix with the specified column set to values.
      Throws:
      IllegalArgumentException - If the values vector has a different length than the number of rows of this matrix.
      IndexOutOfBoundsException - If colIndex < 0 || colIndex >= this.numCols.

    • setRow

      public CooMatrix setRow(CooVector values, int rowIndex)
      Sets a row of this matrix at the given index to the specified values.
      Specified by:
      setRow in interface MatrixMixin<CooMatrix,Matrix,CooVector,Double>
      Parameters:
      values - New values for the row.
      rowIndex - The index of the row which is to be set.
      Returns:
      A copy of this matrix with the specified row set to values.
      Throws:
      IllegalArgumentException - If the values vector has a different length than the number of rows of this matrix.

    • setRow

      public CooMatrix setRow(double[] row, int rowIdx)
      Sets a specified row of this matrix to an array.
      Parameters:
      row - Array containing values 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.

    • toComplex

      public CooCMatrix toComplex()
      Converts this real sparse COO matrix to an equivalent complex sparse COO matrix.
      Returns:
      A complex sparse COO matrix equivalent to this matrix.

    • elemMult

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

    • elemMult

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

    • elemMult

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

    • coalesce

      public CooMatrix coalesce()
      Coalesces this sparse COO matrix. An uncoalesced matrix is a sparse matrix with multiple data for a single index. This method will ensure that each index only has one non-zero value by summing duplicated data. If another form of aggregation other than summing is desired, use coalesce(BinaryOperator).
      Returns:
      A new coalesced sparse COO matrix which is equivalent to this COO matrix.
      See Also:

    • coalesce

      public CooMatrix coalesce(BinaryOperator<Double> aggregator)
      Coalesces this sparse COO matrix. An uncoalesced matrix is a sparse matrix with multiple data for a single index. This method will ensure that each index only has one non-zero value by aggregating duplicated data using aggregator.
      Parameters:
      aggregator - Custom aggregation function to combine multiple.
      Returns:
      A new coalesced sparse COO matrix which is equivalent to this COO matrix.
      See Also:

    • dropZeros

      public CooMatrix dropZeros()
      Drops any explicit zeros in this sparse COO matrix.
      Returns:
      A copy of this COO matrix with any explicitly stored zeros removed.

    • 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.
      Specified by:
      accept in interface MatrixMixin<CooMatrix,Matrix,CooVector,Double>
      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.
      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 CooMatrix. False otherwise.

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Formats this sparse matrix as a human-readable string.
      Overrides:
      toString in class Object
      Returns:
      A human-readable string representing this sparse matrix.