Class CooTensor

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

A real sparse tensor 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 tensor are mutable but the AbstractTensor.shape and total number of non-zero data is fixed.

Sparse tensors allow for the efficient storage of and ops on tensors that contain many zero values.

COO tensors are optimized for hyper-sparse tensors (i.e. tensors which contain almost all zeros relative to the size of the tensor).

A sparse COO tensor is stored as:

  • The full shape of the tensor.
  • The non-zero AbstractTensor.data of the tensor. All other data in the tensor are assumed to be zero. Zero value can also explicitly be stored in AbstractTensor.data.

  • The indices of the non-zero value in the sparse tensor. Many ops assume indices to be sorted in a row-major format (i.e. last index increased fastest) but often this is not explicitly verified.

    The indices array has shape (nnz, rank) where nnz is the number of non-zero data in this sparse tensor and rank is the tensor rank of the tensor. This means indices[i] is the ND index of data[i].

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 tensor are sorted lexicographically. However, this is not explicitly verified. Every operation implemented in this class will preserve the lexicographical sorting.

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

See Also:

  • Field Details

    • indices

      public final int[][] indices
      The non-zero indices of this tensor. Must have shape (nnz, rank).

    • nnz

      public final int nnz
      The number of non-zero data in this tensor.

  • Constructor Details

    • CooTensor

      public CooTensor(Shape shape, double[] entries, int[][] indices)
      Creates a tensor with the specified data and shape.
      Parameters:
      shape - Shape of this tensor.
      entries - Non-zero data of this tensor 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.
      indices -

    • CooTensor

      public CooTensor(Shape shape, List<Double> entries, List<int[]> indices)
      Creates a tensor with the specified data and shape.
      Parameters:
      shape - Shape of this tensor.
      entries - Non-zero data of this tensor 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.
      indices -

    • CooTensor

      public CooTensor(Shape shape)
      Creates a zero matrix with the specified shape.
      Parameters:
      shape - The shape of the zero matrix to construct.

    • CooTensor

      public CooTensor(Shape shape, int[] entries, int[][] indices)
      Creates a sparse COO matrix with the specified shape, non-zero data, and indices.
      Parameters:
      shape - Shape of the matrix to construct.
      entries - Non-zero data of the sparse COO matrix.
      indices - Indices of the non-zero data in the sparse COO matrix.

    • CooTensor

      public CooTensor(CooTensor b)
      Constructs a copy of the specified matrix.
      Parameters:
      b - Matrix to make copy of.

  • Method Details

    • makeLikeTensor

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

    • makeLikeTensor

      public CooTensor makeLikeTensor(Shape shape, double[] entries, int[][] indices)
      Constructs a sparse tensor of the same type as this tensor with the given the shape, non-zero data, and non-zero indices.
      Parameters:
      shape - Shape of the sparse tensor to construct.
      entries - Non-zero data of the sparse tensor to construct.
      indices - Non-zero indices of the sparse tensor to construct.
      Returns:
      A sparse tensor of the same type as this tensor with the given the shape and data.

    • makeLikeTensor

      public CooTensor makeLikeTensor(Shape shape, List<Double> entries, List<int[]> indices)
      Constructs a sparse tensor of the same type as this tensor with the given the shape, non-zero data, and non-zero indices.
      Parameters:
      shape - Shape of the sparse tensor to construct.
      entries - Non-zero data of the sparse tensor to construct.
      indices - Non-zero indices of the sparse tensor to construct.
      Returns:
      A sparse tensor of the same type as this tensor with the given the shape and data.

    • makeDenseTensor

      public Tensor makeDenseTensor(Shape shape, double[] entries)
      Makes a dense tensor with the specified shape and data which is a similar type to this sparse tensor.
      Parameters:
      shape - Shape of the dense tensor.
      entries - Entries of the dense tensor.
      Returns:
      A dense tensor with the specified shape and data which is a similar type to this sparse tensor.

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

    • toComplex

      public CooCTensor toComplex()
      Converts this tensor to an equivalent complex tensor.
      Returns:
      A complex COO tensor whose non-zero data have real component equal to the non-zero data of this tensor and imaginary components zero.

    • toDense

      public Tensor toDense()
      Converts this sparse tensor to an equivalent dense tensor.
      Returns:
      A dense tensor equivalent to this sparse tensor.

    • get

      public Double get(int... indices)
      Gets the element of this tensor at the specified indices.
      Specified by:
      get in class AbstractTensor<CooTensor,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 CooTensor set(Double value, int... index)
      Sets the element of this tensor at the specified indices.
      Specified by:
      set in class AbstractTensor<CooTensor,double[],Double>
      Parameters:
      value - New value to set the specified index of this tensor to.
      index - Indices of the element to set.
      Index - 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 CooTensor flatten()
      Flattens tensor to single dimension while preserving order of data.
      Specified by:
      flatten in class AbstractTensor<CooTensor,double[],Double>
      Returns:
      The flattened tensor.
      See Also:

    • flatten

      public CooTensor flatten(int axis)
      Flattens a tensor along the specified axis.
      Specified by:
      flatten in class AbstractTensor<CooTensor,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 CooTensor reshape(Shape newShape)
      Copies and reshapes this tensor.
      Specified by:
      reshape in class AbstractTensor<CooTensor,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.

    • sub

      public CooTensor sub(Double b)
      Subtracts a scalar value from each non-zero entry of this tensor.
      Specified by:
      sub in interface TensorOverRing<CooTensor,CooTensor,double[],Double>
      Overrides:
      sub in class AbstractDoubleTensor<CooTensor>
      Parameters:
      b - Scalar value in difference.
      Returns:
      The difference of this tensor and the scalar b.

    • subEq

      public void subEq(Double b)
      Subtracts a scalar value from each non-zero entry of this tensor and stores the result in this tensor.
      Specified by:
      subEq in interface TensorOverRing<CooTensor,CooTensor,double[],Double>
      Overrides:
      subEq in class AbstractDoubleTensor<CooTensor>
      Parameters:
      b - Scalar value in difference.

    • add

      public CooTensor add(Double b)
      Adds a scalar field value to each non-zero entry of this tensor.
      Specified by:
      add in interface TensorOverSemiring<CooTensor,CooTensor,double[],Double>
      Overrides:
      add in class AbstractDoubleTensor<CooTensor>
      Parameters:
      b - Scalar field value in sum.
      Returns:
      The sum of this tensor with the scalar b.

    • addEq

      public void addEq(Double b)
      Adds a scalar value to each non-zero entry of this tensor and stores the result in this tensor.
      Specified by:
      addEq in interface TensorOverSemiring<CooTensor,CooTensor,double[],Double>
      Overrides:
      addEq in class AbstractDoubleTensor<CooTensor>
      Parameters:
      b - Scalar field value in sum.

    • add

      public CooTensor add(CooTensor b)
      Computes the element-wise sum between two tensors of the same shape.
      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.

    • add

      public CooCTensor add(CooCTensor b)
      Computes the element-wise sum between two tensors of the same shape.
      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 CooTensor sub(CooTensor b)
      Computes the element-wise difference between two tensors of the same shape.
      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.

    • argmin

      public int[] argmin()
      Finds the indices of the minimum value in this tensor.
      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.
      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.
      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.

    • argmaxAbs

      public int[] argmaxAbs()
      Finds the indices of the maximum absolute value in this tensor.
      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.

    • elemMult

      public CooTensor elemMult(CooTensor b)
      Computes the element-wise multiplication of two tensors of the same shape.
      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.

    • tensorDot

      public Tensor tensorDot(CooTensor 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.
      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.

    • tensorTr

      public CooTensor tensorTr(int axis1, int axis2)

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

      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.

      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.

      NOTE: This is only the product of the non-zero values in this tensor.

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

    • T

      public CooTensor T(int axis1, int axis2)
      Computes the transpose of a tensor by exchanging axis1 and axis2.
      Specified by:
      T in class AbstractTensor<CooTensor,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 CooTensor 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<CooTensor,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:

    • recip

      public CooTensor recip()

      Computes the element-wise reciprocals of the non-zero elements of this sparse tensor.

      Note: This method only computes the reciprocals of the non-zero elements.

      Specified by:
      recip in interface TensorOverField<CooTensor,CooTensor,double[],Double>
      Overrides:
      recip in class AbstractDoubleTensor<CooTensor>
      Returns:
      A tensor containing the reciprocal non-zero elements of this tensor.

    • copy

      public CooTensor copy()
      Creates a deep copy of this tensor.
      Overrides:
      copy in class AbstractDoubleTensor<CooTensor>
      Returns:
      A deep copy of this tensor.

    • add

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

    • sub

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

    • div

      public CooTensor div(CooTensor b)

      Computes the element-wise quotient between two tensors.

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

      Parameters:
      b - Second tensor in the element-wise quotient.
      Returns:
      The element-wise quotient of this tensor with b.

    • sortIndices

      public void sortIndices()
      Sorts the indices of this tensor in lexicographical order while maintaining the associated value for each index.

    • coalesce

      public CooTensor coalesce()
      Coalesces this sparse COO tensor. An uncoalesced tensor is a sparse tensor 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 tensor which is equivalent to this COO tensor.
      See Also:

    • coalesce

      public CooTensor coalesce(BinaryOperator<Double> aggregator)
      Coalesces this sparse COO tensor. An uncoalesced tensor is a sparse tensor 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 tensor which is equivalent to this COO tensor.
      See Also:

    • dropZeros

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

    • equals

      public boolean equals(Object object)
      Checks if an object is equal to this tensor object.
      Overrides:
      equals in class Object
      Parameters:
      object - Object to check equality with this tensor.
      Returns:
      True if the two tensors have the same shape, are numerically equivalent, and are of type CooTensor. False otherwise.

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()

      Formats this sparse COO tensor as a human-readable string specifying the full shape, non-zero data, and non-zero indices.

      Overrides:
      toString in class Object
      Returns:
      A human-readable string specifying the full shape, non-zero data, and non-zero indices of this tensor.