com.yahoo.tensor

Interface Tensor

All Known Implementing Classes:

IndexedTensor, MappedTensor, MixedTensor

@Beta
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 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 order.

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

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	Tensor.Builder
static class	Tensor.Cell

Method Summary

Modifier and Type	Method and Description
default Tensor	add(Tensor argument)
default Tensor	approxEqual(Tensor argument)
static boolean	approxEquals(double x, double y)
static boolean	approxEquals(double x, double y, double tolerance)
default Tensor	argmax(String dimension)
default Tensor	argmin(String dimension)
default double	asDouble() Returns the value of this as a double if it has no dimensions and one value
default Tensor	atan2(Tensor argument)
default Tensor	avg()
default Tensor	avg(List<String> dimensions)
default Tensor	avg(String dimension)
Iterator<Tensor.Cell>	cellIterator() Returns the cell of this in some undefined order
Map<TensorAddress,Double>	cells() Returns an immutable map of the cells of this in no particular order.
default Tensor	concat(double argument, String dimension)
default Tensor	concat(Tensor argument, String dimension)
static String	contentToString(Tensor tensor)
default Tensor	count()
default Tensor	count(List<String> dimensions)
default Tensor	count(String dimension)
static Tensor	diag(TensorType type)
default Tensor	divide(Tensor argument)
default Tensor	equal(Tensor argument)
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.
static boolean	equals(Tensor a, Tensor b) Implement here to make this work across implementations.
default Tensor	fmod(Tensor argument)
static Tensor	from(String tensorString) Returns a tensor instance containing the given data on the standard string format returned by toString.
static Tensor	from(String tensorType, String tensorString) Returns a tensor instance containing the given data on the standard string format returned by toString
static Tensor	from(TensorType type, String tensorString) Returns a tensor instance containing the given data on the standard string format returned by toString
static Tensor	generate(TensorType type, Function<List<Long>,Double> valueSupplier)
double	get(TensorAddress address) Returns the value of a cell, or NaN if this cell does not exist/have no value
default boolean	isEmpty() Returns whether this have any cells
default Tensor	join(Tensor argument, DoubleBinaryOperator combinator)
default Tensor	l1Normalize(String dimension)
default Tensor	l2Normalize(String dimension)
default Tensor	larger(Tensor argument)
default Tensor	largerOrEqual(Tensor argument)
default Tensor	ldexp(Tensor argument)
default Tensor	map(DoubleUnaryOperator mapper)
default Tensor	matmul(Tensor argument, String dimension)
default Tensor	max()
default Tensor	max(List<String> dimensions)
default Tensor	max(String dimension)
default Tensor	max(Tensor argument)
default Tensor	min()
default Tensor	min(List<String> dimensions)
default Tensor	min(String dimension)
default Tensor	min(Tensor argument)
default Tensor	multiply(Tensor argument)
default Tensor	notEqual(Tensor argument)
default Tensor	pow(Tensor argument)
default Tensor	prod()
default Tensor	prod(List<String> dimensions)
default Tensor	prod(String dimension)
static Tensor	random(TensorType type)
static Tensor	range(TensorType type)
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
default Tensor	reduce(Reduce.Aggregator aggregator, String... dimensions) Aggregates cells over a set of dimensions, or over all dimensions if no dimensions are specified
default Tensor	rename(List<String> fromDimensions, List<String> toDimensions)
default Tensor	rename(String fromDimension, String toDimension)
long	size() Returns the number of cells in this
default Tensor	smaller(Tensor argument)
default Tensor	smallerOrEqual(Tensor argument)
default Tensor	softmax(String dimension)
default Tensor	subtract(Tensor argument)
default Tensor	sum()
default Tensor	sum(List<String> dimensions)
default Tensor	sum(String dimension)
static String	toStandardString(Tensor tensor) Call this from toString in implementations to return the standard string format.
String	toString() Returns this tensor on the form {address1:value1,address2:value2,...} where each address is on the form {dimension1:label1,dimension2:label2,...}, and values are numbers.
TensorType	type()
Iterator<Double>	valueIterator() Returns the values of this in some undefined order
default Tensor	xwPlusB(Tensor w, Tensor b, String dimension)

Method Detail

type

TensorType type()

isEmpty

default boolean isEmpty()

Returns whether this have any cells

size

long size()

Returns the number of cells in this

get

double get(TensorAddress address)

Returns the value of a cell, or NaN if this cell does not exist/have no value

cellIterator

Iterator<Tensor.Cell> cellIterator()

Returns the cell of this in some undefined order

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

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)

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)

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)

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)

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)

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)

toString

String toString()

Returns this tensor on the form {address1:value1,address2:value2,...} where each address is on the form {dimension1:label1,dimension2:label2,...}, and values are numbers.

Cells are listed in the natural order of tensor addresses: Increasing size primarily and by element lexical order secondarily.

Note that while this is suggestive of JSON, it is not JSON.

Overrides:

toString in class Object

toStandardString

static String toStandardString(Tensor tensor)

Call this from toString in implementations to return the standard string format. (toString cannot be a default method because default methods cannot override super methods).

Parameters:

tensor - the tensor to return the standard string format of

Returns:

the tensor on the standard string format

contentToString

static String contentToString(Tensor tensor)

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

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 standard string format returned by toString

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 standard string format returned by toString

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 standard string format returned by toString. If a type is not specified it is derived from the first cell of the tensor