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 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	Description
static interface	Tensor.Builder
static class	Tensor.Cell

Method Summary

Modifier and Type	Method	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(java.lang.String dimension)
default Tensor	argmin(java.lang.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(java.lang.String dimension)
default Tensor	avg(java.util.List<java.lang.String> dimensions)
java.util.Iterator<Tensor.Cell>	cellIterator()	Returns the cell of this in some undefined order.
java.util.Map<TensorAddress,java.lang.Double>	cells()	Returns an immutable map of the cells of this in no particular order.
default Tensor	concat(double argument, java.lang.String dimension)
default Tensor	concat(Tensor argument, java.lang.String dimension)
static java.lang.String	contentToString(Tensor tensor)
default Tensor	count()
default Tensor	count(java.lang.String dimension)
default Tensor	count(java.util.List<java.lang.String> dimensions)
static Tensor	diag(TensorType type)
default Tensor	divide(Tensor argument)
default Tensor	equal(Tensor argument)
static boolean	equals(Tensor a, Tensor b)	Implement here to make this work across implementations.
boolean	equals(java.lang.Object o)	Returns whether this tensor and the given tensor is mathematically equal: That they have the same dimension *names* and the same content.
default Tensor	fmod(Tensor argument)
static Tensor	from(double value)	Returns a double as a tensor: A dimensionless tensor containing the value as its cell
static Tensor	from(TensorType type, java.lang.String tensorString)	Returns a tensor instance containing the given data on the standard string format returned by toString
static Tensor	from(java.lang.String tensorString)	Returns a tensor instance containing the given data on the standard string format returned by toString.
static Tensor	from(java.lang.String tensorType, java.lang.String tensorString)	Returns a tensor instance containing the given data on the standard string format returned by toString
static Tensor	generate(TensorType type, java.util.function.Function<java.util.List<java.lang.Long>,java.lang.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, java.util.function.DoubleBinaryOperator combinator)
default Tensor	l1Normalize(java.lang.String dimension)
default Tensor	l2Normalize(java.lang.String dimension)
default Tensor	larger(Tensor argument)
default Tensor	largerOrEqual(Tensor argument)
default java.util.List<Tensor.Cell>	largest()	Returns the cell(s) of this tensor having the highest value
default Tensor	ldexp(Tensor argument)
default Tensor	map(java.util.function.DoubleUnaryOperator mapper)
default Tensor	matmul(Tensor argument, java.lang.String dimension)
default Tensor	max()
default Tensor	max(Tensor argument)
default Tensor	max(java.lang.String dimension)
default Tensor	max(java.util.List<java.lang.String> dimensions)
Tensor	merge(java.util.function.DoubleBinaryOperator op, java.util.Map<TensorAddress,java.lang.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.
default Tensor	min()
default Tensor	min(Tensor argument)
default Tensor	min(java.lang.String dimension)
default Tensor	min(java.util.List<java.lang.String> dimensions)
default Tensor	modify(java.util.function.DoubleBinaryOperator op, java.util.Map<TensorAddress,java.lang.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.
default Tensor	multiply(Tensor argument)
default Tensor	notEqual(Tensor argument)
default Tensor	pow(Tensor argument)
default Tensor	prod()
default Tensor	prod(java.lang.String dimension)
default Tensor	prod(java.util.List<java.lang.String> dimensions)
static Tensor	random(TensorType type)
static Tensor	range(TensorType type)
default Tensor	reduce(Reduce.Aggregator aggregator, java.lang.String... dimensions)	Aggregates cells over a set of dimensions, or over all dimensions if no dimensions are specified
default Tensor	reduce(Reduce.Aggregator aggregator, java.util.List<java.lang.String> dimensions)	Aggregates cells over a set of dimensions, or over all dimensions if no dimensions are specified
Tensor	remove(java.util.Set<TensorAddress> addresses)	Returns a new tensor where existing cells in this tensor have been removed according to the given set of addresses.
default Tensor	rename(java.lang.String fromDimension, java.lang.String toDimension)
default Tensor	rename(java.util.List<java.lang.String> fromDimensions, java.util.List<java.lang.String> toDimensions)
long	size()	Returns the number of cells in this
default Tensor	smaller(Tensor argument)
default Tensor	smallerOrEqual(Tensor argument)
default java.util.List<Tensor.Cell>	smallest()	Returns the cell(s) of this tensor having the lowest value
default Tensor	softmax(java.lang.String dimension)
default Tensor	subtract(Tensor argument)
default Tensor	sum()
default Tensor	sum(java.lang.String dimension)
default Tensor	sum(java.util.List<java.lang.String> dimensions)
static java.lang.String	toStandardString(Tensor tensor)	Call this from toString in implementations to return the standard string format.
java.lang.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()
java.util.Iterator<java.lang.Double>	valueIterator()	Returns the values of this in some undefined order
Tensor	withType(TensorType type)	Returns this tensor with the given type if types are compatible
default Tensor	xwPlusB(Tensor w, Tensor b, java.lang.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

java.util.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

java.util.Iterator<java.lang.Double> valueIterator()

Returns the values of this in some undefined order

cells

java.util.Map<TensorAddress,java.lang.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:

java.lang.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:

java.lang.IllegalArgumentException - if types are not compatible

modify

default Tensor modify(java.util.function.DoubleBinaryOperator op,
                      java.util.Map<TensorAddress,java.lang.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 of existing cells are thus ignored.

Parameters:

op - the modifying function

cells - the cells to modify

Returns:

a new tensor with modified cells

merge

Tensor merge(java.util.function.DoubleBinaryOperator op,
             java.util.Map<TensorAddress,java.lang.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. In contrast to modify(java.util.function.DoubleBinaryOperator, java.util.Map<com.yahoo.tensor.TensorAddress, java.lang.Double>), previously non-existing cells are added to this tensor. Only valid for sparse or mixed tensors.

Parameters:

op - how to update overlapping cells

cells - cells to merge with this tensor

Returns:

a new tensor where this tensor is merged with the other

remove

Tensor remove(java.util.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 sparse or mixed tensors. For mixed tensors, addresses are assumed to only contain the sparse dimensions, as the entire dense subspace is removed.

Parameters:

addresses - list of addresses to remove

Returns:

a new tensor where cells have been removed

map

default Tensor map(java.util.function.DoubleUnaryOperator mapper)

reduce

default Tensor reduce(Reduce.Aggregator aggregator,
                      java.lang.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,
                      java.util.List<java.lang.String> dimensions)

Aggregates cells over a set of dimensions, or over all dimensions if no dimensions are specified

join

default Tensor join(Tensor argument,
                    java.util.function.DoubleBinaryOperator combinator)

rename

default Tensor rename(java.lang.String fromDimension,
                      java.lang.String toDimension)

concat

default Tensor concat(double argument,
                      java.lang.String dimension)

concat

default Tensor concat(Tensor argument,
                      java.lang.String dimension)

rename

default Tensor rename(java.util.List<java.lang.String> fromDimensions,
                      java.util.List<java.lang.String> toDimensions)

generate

static Tensor generate(TensorType type,
                       java.util.function.Function<java.util.List<java.lang.Long>,java.lang.Double> valueSupplier)

l1Normalize

default Tensor l1Normalize(java.lang.String dimension)

l2Normalize

default Tensor l2Normalize(java.lang.String dimension)

matmul

default Tensor matmul(Tensor argument,
                      java.lang.String dimension)

softmax

default Tensor softmax(java.lang.String dimension)

xwPlusB

default Tensor xwPlusB(Tensor w,
                       Tensor b,
                       java.lang.String dimension)

argmax

default Tensor argmax(java.lang.String dimension)

argmin

default Tensor argmin(java.lang.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(java.lang.String dimension)

avg

default Tensor avg(java.util.List<java.lang.String> dimensions)

count

default Tensor count()

count

default Tensor count(java.lang.String dimension)

count

default Tensor count(java.util.List<java.lang.String> dimensions)

max

default Tensor max()

max

default Tensor max(java.lang.String dimension)

max

default Tensor max(java.util.List<java.lang.String> dimensions)

min

default Tensor min()

min

default Tensor min(java.lang.String dimension)

min

default Tensor min(java.util.List<java.lang.String> dimensions)

prod

default Tensor prod()

prod

default Tensor prod(java.lang.String dimension)

prod

default Tensor prod(java.util.List<java.lang.String> dimensions)

sum

default Tensor sum()

sum

default Tensor sum(java.lang.String dimension)

sum

default Tensor sum(java.util.List<java.lang.String> dimensions)

largest

default java.util.List<Tensor.Cell> largest()

Returns the cell(s) of this tensor having the highest value

smallest

default java.util.List<Tensor.Cell> smallest()

Returns the cell(s) of this tensor having the lowest value

toString

java.lang.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 java.lang.Object

toStandardString

static java.lang.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 java.lang.String contentToString(Tensor tensor)

equals

boolean equals(java.lang.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 java.lang.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,
                   java.lang.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(java.lang.String tensorType,
                   java.lang.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(java.lang.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

from

static Tensor from(double value)

Returns a double as a tensor: A dimensionless tensor containing the value as its cell