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
All Methods Static Methods Instance Methods Abstract Methods Default Methods 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 valuedefault 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 cellstatic Tensor
from(TensorType type, java.lang.String tensorString)
Returns a tensor instance containing the given data on the standard string format returned by toStringstatic 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 toStringstatic 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 valuedefault boolean
isEmpty()
Returns whether this have any cellsdefault 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 valuedefault 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 specifieddefault 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 specifiedTensor
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 thisdefault 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 valuedefault 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 orderTensor
withType(TensorType type)
Returns this tensor with the given type if types are compatibledefault 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 functioncells
- 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 tomodify(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 cellscells
- 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
-
rename
default Tensor rename(java.lang.String fromDimension, java.lang.String toDimension)
-
concat
default Tensor concat(double 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)
-
softmax
default Tensor softmax(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)
-
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 classjava.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 classjava.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 returntensorString
- 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 inTensorType.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
-
-