diff options
Diffstat (limited to 'vespajlib')
4 files changed, 34 insertions, 36 deletions
diff --git a/vespajlib/src/main/java/com/yahoo/tensor/IndexedTensor.java b/vespajlib/src/main/java/com/yahoo/tensor/IndexedTensor.java index 1da013de012..f5ef88016ac 100644 --- a/vespajlib/src/main/java/com/yahoo/tensor/IndexedTensor.java +++ b/vespajlib/src/main/java/com/yahoo/tensor/IndexedTensor.java @@ -16,7 +16,12 @@ import java.util.Set; import java.util.function.DoubleBinaryOperator; /** - * An indexed (dense) tensor backed by an array. + * An indexed (dense) tensor. + * <p> + * Some methods on indexed tensors make use of a <b>standard value order</b>: Cells are ordered by increasing + * index where dimensions to the right are incremented before indexes to the left, where the order of dimensions are + * alphabetical by name. In consequence, tensor value ordering is independent of the order in which dimensions are + * specified, and the values of the right-most dimension are adjacent. * * @author bratseth */ @@ -34,9 +39,7 @@ public abstract class IndexedTensor implements Tensor { } /** - * Returns an iterator over the cells of this. - * Cells are returned in order of increasing indexes in each dimension, increasing - * indexes of later dimensions in the dimension type before earlier. + * Returns an iterator over the cells of this in the <i>standard value order</i>. */ @Override public Iterator<Cell> cellIterator() { @@ -58,11 +61,7 @@ public abstract class IndexedTensor implements Tensor { return new SubspaceIterator(iterateDimensions, startAddress, iterationSizes); } - /** - * Returns an iterator over the values of this. - * Values are returned in order of increasing indexes in each dimension, increasing - * indexes of later dimensions in the dimension type before earlier. - */ + /** Returns an iterator over the values of this returned in the <i>standard value order</i> */ @Override public Iterator<Double> valueIterator() { return new ValueIterator(); @@ -70,8 +69,8 @@ public abstract class IndexedTensor implements Tensor { /** * Returns an iterator over value iterators where the outer iterator is over each unique value of the dimensions - * given and the inner iterator is over each unique value of the rest of the dimensions, in the same order as - * other iterator. + * given and the inner iterator is over each unique value of the rest of the dimensions, in the + * <i>standard value order</i> * * @param dimensions the names of the dimensions of the superspace * @param sizes the size of each dimension in the space we are returning values for, containing @@ -120,8 +119,7 @@ public abstract class IndexedTensor implements Tensor { } /** - * Returns the value at the given index as a double by direct lookup. Only use - * if you know the underlying data layout. + * Returns the value at the given <i>standard value order</i> index as a double. * * @param valueIndex the direct index into the underlying data. * @throws IllegalArgumentException if index is out of bounds @@ -129,8 +127,7 @@ public abstract class IndexedTensor implements Tensor { public abstract double get(long valueIndex); /** - * Returns the value at the given index as a float by direct lookup. Only use - * if you know the underlying data layout. + * Returns the value at the given <i>standard value order</i> index as a float. * * @param valueIndex the direct index into the underlying data. * @throws IllegalArgumentException if index is out of bounds @@ -310,7 +307,8 @@ public abstract class IndexedTensor implements Tensor { * Creates a builder initialized with the given values * * @param type the type of the tensor to build - * @param values the initial values of the tensor. This <b>transfers ownership</b> of the value array - it + * @param values the initial values of the tensor in the <i>standard value order</i>. + * This <b>transfers ownership</b> of the value array - it * must not be further mutated by the caller */ public static Builder of(TensorType type, DimensionSizes sizes, float[] values) { @@ -329,7 +327,8 @@ public abstract class IndexedTensor implements Tensor { * Creates a builder initialized with the given values * * @param type the type of the tensor to build - * @param values the initial values of the tensor. This <b>transfers ownership</b> of the value array - it + * @param values the initial values of the tensor in the <i>standard value order</i>. + * This <b>transfers ownership</b> of the value array - it * must not be further mutated by the caller */ public static Builder of(TensorType type, DimensionSizes sizes, double[] values) { @@ -411,10 +410,10 @@ public abstract class IndexedTensor implements Tensor { DimensionSizes sizes() { return sizes; } - /** Sets a value by its right-adjacent traversal position */ + /** Sets a value by its <i>standard value order</i> index */ public abstract void cellByDirectIndex(long index, double value); - /** Sets a value by its right-adjacent traversal position */ + /** Sets a value by its <i>standard value order</i> index */ public abstract void cellByDirectIndex(long index, float value); } @@ -672,7 +671,7 @@ public abstract class IndexedTensor implements Tensor { * @param iterateDimensions the dimensions to iterate over, given as indexes in the dimension order of the * type of the tensor this iterates over. This iterator will iterate over these * dimensions to exhaustion in the order given (the first dimension index given is - * incremented to exhaustion first (i.e is etc.), while other dimensions will be held + * incremented to exhaustion first etc., while other dimensions will be held * at a constant position. * This may be any subset of the dimensions given by address and dimensionSizes. * This is treated as immutable. diff --git a/vespajlib/src/main/java/com/yahoo/tensor/Tensor.java b/vespajlib/src/main/java/com/yahoo/tensor/Tensor.java index 8b0aaa64551..afd82751137 100644 --- a/vespajlib/src/main/java/com/yahoo/tensor/Tensor.java +++ b/vespajlib/src/main/java/com/yahoo/tensor/Tensor.java @@ -295,21 +295,16 @@ public interface Tensor { // ----------------- serialization /** - * Returns this tensor on the form - * <code>{address1:value1,address2:value2,...}</code> - * where each address is on the form <code>{dimension1:label1,dimension2:label2,...}</code>, - * and values are numbers. - * <p> - * Cells are listed in the natural order of tensor addresses: Increasing size primarily - * and by element lexical order secondarily. - * <p> - * Note that while this is suggestive of JSON, it is not JSON. + * Returns this tensor on the + * <a href="https://docs.vespa.ai/documentation/reference/tensor.html#tensor-literal-form">tensor literal form</a> + * with type included. */ @Override String toString(); /** - * Call this from toString in implementations to return the standard string format. + * Call this from toString in implementations to return this tensor on the + * <a href="https://docs.vespa.ai/documentation/reference/tensor.html#tensor-literal-form">tensor literal form</a>. * (toString cannot be a default method because default methods cannot override super methods). * * @param tensor the tensor to return the standard string format of @@ -345,6 +340,7 @@ public interface Tensor { * Returns whether this tensor and the given tensor is mathematically equal: * That they have the same dimension *names* and the same content. */ + @Override boolean equals(Object o); /** @@ -381,7 +377,8 @@ public interface Tensor { // ----------------- Factories /** - * Returns a tensor instance containing the given data on the standard string format returned by toString + * Returns a tensor instance containing the given data on the + * <a href="https://docs.vespa.ai/documentation/reference/tensor.html#tensor-literal-form">tensor literal form</a>. * * @param type the type of the tensor to return * @param tensorString the tensor on the standard tensor string format @@ -391,7 +388,8 @@ public interface Tensor { } /** - * Returns a tensor instance containing the given data on the standard string format returned by toString + * Returns a tensor instance containing the given data on the + * <a href="https://docs.vespa.ai/documentation/reference/tensor.html#tensor-literal-form">tensor literal form</a>. * * @param tensorType the type of the tensor to return, as a string on the tensor type format, given in * {@link TensorType#fromSpec} @@ -402,8 +400,8 @@ public interface Tensor { } /** - * 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 + * Returns a tensor instance containing the given data on the + * <a href="https://docs.vespa.ai/documentation/reference/tensor.html#tensor-literal-form">tensor literal form</a>. */ static Tensor from(String tensorString) { return TensorParser.tensorFrom(tensorString, Optional.empty()); diff --git a/vespajlib/src/main/java/com/yahoo/tensor/TensorType.java b/vespajlib/src/main/java/com/yahoo/tensor/TensorType.java index d64a62143f4..bafec70be59 100644 --- a/vespajlib/src/main/java/com/yahoo/tensor/TensorType.java +++ b/vespajlib/src/main/java/com/yahoo/tensor/TensorType.java @@ -98,7 +98,8 @@ public class TensorType { } /** - * Returns a tensor type instance from a string on the format + * Returns a tensor type instance from a + * <a href="https://docs.vespa.ai/documentation/reference/tensor.html#tensor-type-spec">tensor type spec</a>: * <code>tensor(dimension1, dimension2, ...)</code> * where each dimension is either * <ul> diff --git a/vespajlib/src/main/java/com/yahoo/tensor/serialization/JsonFormat.java b/vespajlib/src/main/java/com/yahoo/tensor/serialization/JsonFormat.java index c73ff03a0eb..fa022e2bdd1 100644 --- a/vespajlib/src/main/java/com/yahoo/tensor/serialization/JsonFormat.java +++ b/vespajlib/src/main/java/com/yahoo/tensor/serialization/JsonFormat.java @@ -18,7 +18,7 @@ import java.util.Iterator; /** * Writes tensors on the JSON format used in Vespa tensor document fields: - * A JSON map containing a 'cells' array. + * A JSON map containing a 'cells' or 'values' array. * See a http://docs.vespa.ai/documentation/reference/document-json-put-format.html#tensor * * @author bratseth |