Class RingTensor<T extends Ring<T>>

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

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

A RingTensor is a generalization of the RingMatrix, allowing for higher-dimensional data and operations while maintaining the benefits of Ring-based arithmetic and dense storage.

Key Features:

  • Support for standard tensor operations like addition, element-wise multiplication, and reshaping.
  • Conversion methods to other representations, including RingMatrix, RingVector, and COO format.
  • Utility methods for computing properties like rank and shape

Example Usage:

  • Constructing a tensor from a Shape shape and flat data array. This is generally the preferred and most efficient method of constructing a tensor. 
    
 // Constructing a ring tensor from a shape and flat data array.
 Complex128[] data = {
     new RealInt32(1), new RealInt32(2),
     new RealInt32(3), new RealInt32(4),
     new RealInt32(5), new RealInt32(6),
     new RealInt32(7), new RealInt32(8)
 };

 RingTensor<RealInt32> tensor = new RingTensor<>(data);
  • Constructing a tensor from an nD array. This is provided for convenience but is generally much less efficient than RingTensor(Shape, T[]). 
    
 // Constructing a complex tensor from a 3D array of complex numbers
 Complex128[][][] complexData = {
     {{ new RealInt32(1), new RealInt32(2) },
     {  new RealInt32(3), new RealInt32(4) }},

     {{ new RealInt32(5), new RealInt32(6) },
     {  new RealInt32(7), new RealInt32(8) }}
 };
 RingTensor<RealInt32> tensor = new RingTensor<>(complexData);
  • Operations with/on tensors. 
    
 // Performing element-wise addition
 RingTensor<RealInt32> result = tensor.add(tensor);

 // Reshape tensor
 RingTensor<RealInt32> reshape = tensor.reshape(new Shape(4, 1, 2));

 // Converting the tensor to a matrix
 RingMatrix<RealInt32> matrix = tensor.toMatrix(new Shape(4, 2));

 // Computing the tensor dot product.
 RingTensor<RealInt32> dot = tensor.tensorDot(tensor,
      new int[]{0, 1},
      new int[]{2, 0}
 );
See Also:

  • Constructor Details

    • RingTensor

      public RingTensor(Shape shape, T[] data)
      Creates a tensor with the specified data and shape.
      Parameters:
      shape - Shape of this tensor.
      data - 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.

    • RingTensor

      public RingTensor(Object nDArray)
      Creates a tensor from an nD array. The tensors shape will be inferred from.
      Parameters:
      nDArray - Array to construct tensor from. Must be a rectangular array.
      Throws:
      IllegalArgumentException - If nDArray is not an array or not rectangular.

    • RingTensor

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

  • Method Details

    • makeLikeCooTensor

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

    • makeLikeTensor

      public RingTensor<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<RingTensor<T extends Ring<T>>,RingTensor<T extends Ring<T>>,T extends Ring<T>[],T extends Ring<T>>
      Specified by:
      makeLikeTensor in class AbstractTensor<RingTensor<T extends Ring<T>>,T extends Ring<T>[],T extends Ring<T>>
      Parameters:
      shape - Shape of the tensor to construct.
      entries - Entries of the tensor to construct.
      Returns:
      A tensor of the same type and with the same non-zero indices as this tensor with the given the shape and data.

    • toVector

      public RingVector<T> toVector()
      Converts this tensor to an equivalent vector. If this tensor is not rank 1, then it will be flattened.
      Returns:
      A vector equivalent of this tensor.

    • toMatrix

      public RingMatrix<T> toMatrix(Shape matShape)
      Converts this tensor to a matrix with the specified shape.
      Parameters:
      matShape - Shape of the resulting matrix. Must be broadcastable with the shape of this tensor.
      Returns:
      A matrix of shape matShape with the values of this tensor.
      Throws:
      LinearAlgebraException - If matShape is not of rank 2.

    • abs

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

    • 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 RingTensor. false otherwise.

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Formats this tensor as a human-readable string. Specifically, a string containing the shape and flattened data of this tensor.
      Overrides:
      toString in class Object
      Returns:
      A human-readable string representing this tensor.