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 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
    • Method Detail

      • 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
      • 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)
      • merge

        default Tensor merge​(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)
      • argmax

        default Tensor argmax​(java.lang.String dimension)
      • argmin

        default Tensor argmin​(java.lang.String dimension)
      • largerOrEqual

        default Tensor largerOrEqual​(Tensor argument)
      • smallerOrEqual

        default Tensor smallerOrEqual​(Tensor argument)
      • approxEqual

        default Tensor approxEqual​(Tensor argument)
      • 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​(java.lang.String dimension)
      • max

        default Tensor max​(java.util.List<java.lang.String> dimensions)
      • 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​(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 tensor literal form with type included.
        Overrides:
        toString in class java.lang.Object
      • toStandardString

        static java.lang.String toStandardString​(Tensor tensor)
        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
        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 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​(java.lang.String tensorType,
                           java.lang.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​(java.lang.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