Package com.yahoo.tensor

Interface Tensor

All Known Implementing Classes:
IndexedTensor, MappedTensor, MixedTensor
public interface Tensor
A multidimensional array which can be used in computations.

A tensor consists of a set of dimension names and a set of cells containing scalar values. Each cell is identified by its address, which consists of a set of dimension-label pairs which defines the location of that cell. Both dimensions and labels are string on the form of an identifier or integer.

The size of the set of dimensions of a tensor is called its rank.

In contrast to regular mathematical formulations of tensors, this definition of a tensor allows sparseness as there is no built-in notion of a contiguous space, and even in cases where a space is implied (such as when address labels are integers), there is no requirement that every implied cell has a defined value. Undefined values have no define representation as they are never observed.

Tensors can be read and serialized to and from a string form documented in the toString() method.

Author:
bratseth

  • Field Details

    • invalidIndex

      static final int invalidIndex
      The constant signaling a nonexisting value in operations addressing tensor values by index.
      See Also:

  • Method Details

    • type

      TensorType type()

    • isEmpty

      default boolean isEmpty()
      Returns whether this have any cells

    • size

      default long size()
      Returns the number of cells in this, allowing for very large tensors. Prefer sizeAsInt in implementations that cannot handle sizes outside the int range.

    • sizeAsInt

      default int sizeAsInt()
      Returns the size of this as an int or throws an exception if it is too large to fit in an int. Prefer this over size() with implementations that only handle sizes in the int range.
      Throws:
      IndexOutOfBoundsException - if the size is too large to fit in an int

    • get

      double get(TensorAddress address)
      Returns the value of a cell, or 0.0 if this cell does not exist

    • has

      boolean has(TensorAddress address)
      Returns true if this cell exists

    • getAsDouble

      Double getAsDouble(TensorAddress address)
      Returns the value at this address, or null of it does not exist.

    • cellIterator

      Iterator<Tensor.Cell> cellIterator()
      Returns the cell of this in some undefined order. A cell instances is only valid until next() is called. Call detach() on the cell to obtain a long-lived instance.

    • valueIterator

      Iterator<Double> valueIterator()
      Returns the values of this in some undefined order

    • cells

      Map<TensorAddress,Double> cells()
      Returns an immutable map of the cells of this in no particular order. This may be expensive for some implementations - avoid when possible

    • asDouble

      default double asDouble()
      Returns the value of this as a double if it has no dimensions and one value
      Throws:
      IllegalStateException - if this does not have zero dimensions and one value

    • withType

      Tensor withType(TensorType type)
      Returns this tensor with the given type if types are compatible
      Throws:
      IllegalArgumentException - if types are not compatible

    • modify

      default Tensor modify(DoubleBinaryOperator op, Map<TensorAddress,Double> cells)
      Returns a new tensor where existing cells in this tensor have been modified according to the given operation and cells in the given map. Cells in the map outside existing cells are thus ignored.
      Parameters:
      op - the modifying function
      cells - the cells to modify
      Returns:
      a new tensor with modified cells

    • remove

      Tensor remove(Set<TensorAddress> addresses)
      Returns a new tensor where existing cells in this tensor have been removed according to the given set of addresses. Only valid for mapped or mixed tensors. For mixed tensors, addresses are assumed to only contain the mapped dimensions, as the entire indexed subspace is removed.
      Parameters:
      addresses - list of addresses to remove
      Returns:
      a new tensor where cells have been removed

    • map

      default Tensor map(DoubleUnaryOperator mapper)

    • reduce

      default Tensor reduce(Reduce.Aggregator aggregator, String... dimensions)
      Aggregates cells over a set of dimensions, or over all dimensions if no dimensions are specified

    • reduce

      default Tensor reduce(Reduce.Aggregator aggregator, List<String> dimensions)
      Aggregates cells over a set of dimensions, or over all dimensions if no dimensions are specified

    • join

      default Tensor join(Tensor argument, DoubleBinaryOperator combinator)

    • merge

      default Tensor merge(Tensor argument, DoubleBinaryOperator combinator)

    • rename

      default Tensor rename(String fromDimension, String toDimension)

    • concat

      default Tensor concat(double argument, String dimension)

    • concat

      default Tensor concat(Tensor argument, String dimension)

    • rename

      default Tensor rename(List<String> fromDimensions, List<String> toDimensions)

    • generate

      static Tensor generate(TensorType type, Function<List<Long>,Double> valueSupplier)

    • cellCast

      default Tensor cellCast(TensorType.Value valueType)

    • l1Normalize

      default Tensor l1Normalize(String dimension)

    • l2Normalize

      default Tensor l2Normalize(String dimension)

    • matmul

      default Tensor matmul(Tensor argument, String dimension)

    • softmax

      default Tensor softmax(String dimension)

    • xwPlusB

      default Tensor xwPlusB(Tensor w, Tensor b, String dimension)

    • expand

      default Tensor expand(String dimension)

    • argmax

      default Tensor argmax(String dimension)

    • argmin

      default Tensor argmin(String dimension)

    • diag

      static Tensor diag(TensorType type)

    • random

      static Tensor random(TensorType type)

    • range

      static Tensor range(TensorType type)

    • multiply

      default Tensor multiply(Tensor argument)

    • add

      default Tensor add(Tensor argument)

    • divide

      default Tensor divide(Tensor argument)

    • subtract

      default Tensor subtract(Tensor argument)

    • max

      default Tensor max(Tensor argument)

    • min

      default Tensor min(Tensor argument)

    • atan2

      default Tensor atan2(Tensor argument)

    • pow

      default Tensor pow(Tensor argument)

    • fmod

      default Tensor fmod(Tensor argument)

    • ldexp

      default Tensor ldexp(Tensor argument)

    • larger

      default Tensor larger(Tensor argument)

    • largerOrEqual

      default Tensor largerOrEqual(Tensor argument)

    • smaller

      default Tensor smaller(Tensor argument)

    • smallerOrEqual

      default Tensor smallerOrEqual(Tensor argument)

    • equal

      default Tensor equal(Tensor argument)

    • notEqual

      default Tensor notEqual(Tensor argument)

    • approxEqual

      default Tensor approxEqual(Tensor argument)

    • bit

      default Tensor bit(Tensor argument)

    • hamming

      default Tensor hamming(Tensor argument)

    • avg

      default Tensor avg()

    • avg

      default Tensor avg(String dimension)

    • avg

      default Tensor avg(List<String> dimensions)

    • count

      default Tensor count()

    • count

      default Tensor count(String dimension)

    • count

      default Tensor count(List<String> dimensions)

    • max

      default Tensor max()

    • max

      default Tensor max(String dimension)

    • max

      default Tensor max(List<String> dimensions)

    • median

      default Tensor median()

    • median

      default Tensor median(String dimension)

    • median

      default Tensor median(List<String> dimensions)

    • min

      default Tensor min()

    • min

      default Tensor min(String dimension)

    • min

      default Tensor min(List<String> dimensions)

    • prod

      default Tensor prod()

    • prod

      default Tensor prod(String dimension)

    • prod

      default Tensor prod(List<String> dimensions)

    • sum

      default Tensor sum()

    • sum

      default Tensor sum(String dimension)

    • sum

      default Tensor sum(List<String> dimensions)

    • largest

      default List<Tensor.Cell> largest()
      Returns the cell(s) of this tensor having the highest value

    • smallest

      default List<Tensor.Cell> smallest()
      Returns the cell(s) of this tensor having the lowest value

    • toString

      String toString()
      Returns this tensor on the tensor literal form with type included.
      Overrides:
      toString in class Object

    • toString

      String toString(boolean withType, boolean shortForms)
      Returns this tensor on the tensor literal form.
      Parameters:
      withType - whether to prefix the value by the type of this
      shortForms - whether to use short forms where applicable, or always using the verbose form

    • toAbbreviatedString

      default String toAbbreviatedString()
      Returns an abbreviated string representation of this tensor suitable for human-readable messages

    • toAbbreviatedString

      String toAbbreviatedString(boolean withType, boolean shortForms)
      Returns an abbreviated string representation of this tensor suitable for human-readable messages
      Parameters:
      withType - whether to prefix the value by the type of this
      shortForms - whether to use short forms where applicable, or always using the verbose form

    • toStandardString

      static String toStandardString(Tensor tensor, boolean withType, boolean shortForms, long maxCells)
      Call this from toString in implementations to return this tensor on the tensor literal form. (toString cannot be a default method because default methods cannot override super methods).
      Parameters:
      tensor - the tensor to return the standard string format of
      withType - whether the type should be prepended to the content
      maxCells - the max number of cells to output, after which just , "..." is output to represent the rest of the cells
      Returns:
      the tensor on the standard string format

    • valueToString

      static String valueToString(Tensor tensor, boolean shortForms, long maxCells)

    • equals

      boolean equals(Object o)
      Returns whether this tensor and the given tensor is mathematically equal: That they have the same dimension *names* and the same content.
      Overrides:
      equals in class Object

    • hashCode

      int hashCode()
      Returns a hash computed deterministically from the content of this tensor
      Overrides:
      hashCode in class Object

    • equals

      static boolean equals(Tensor a, Tensor b)
      Implement here to make this work across implementations. Implementations must override equals and call this because this is an interface and cannot override equals.

    • approxEquals

      static boolean approxEquals(double x, double y, double tolerance)

    • approxEquals

      static boolean approxEquals(double x, double y)

    • from

      static Tensor from(TensorType type, String tensorString)
      Returns a tensor instance containing the given data on the tensor literal form.
      Parameters:
      type - the type of the tensor to return
      tensorString - the tensor on the standard tensor string format

    • from

      static Tensor from(String tensorType, String tensorString)
      Returns a tensor instance containing the given data on the tensor literal form.
      Parameters:
      tensorType - the type of the tensor to return, as a string on the tensor type format, given in TensorType.fromSpec(java.lang.String)
      tensorString - the tensor on the standard tensor string format

    • from

      static Tensor from(String tensorString)
      Returns a tensor instance containing the given data on the tensor literal form.

    • from

      static Tensor from(double value)
      Returns a double as a tensor: A dimensionless tensor containing the value as its cell