Class Shape

java.lang.Object
org.tensorflow.ndarray.Shape
public final class Shape extends Object
The shape of a Tensor or NdArray.

A Shape defines sizes along its axes. It may contain an unknown size for one of the axes or may be totally unknown, in which case not even the number of axes is known. If the size of an axis is unknown, UNKNOWN_SIZE should be used as its size.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static long
    UNKNOWN_SIZE
    The size of an unknown axis or the total unknown size for an unknown Shape.

  • Method Summary

    Modifier and Type
    Method
    Description
    Shape
    append(long lastDimension)
    Returns a new Shape, with a new last dimension added.
    Shape
    append(Shape other)
    Returns a new Shape, with another Shapes' dimensions appended.
    long[]
    asArray()
    Returns a defensive copy of the this Shape's axes.
    boolean
    equals(Object obj)
    Equals implementation for Shapes.
    long
    get(int i)
    The size of the dimension with the given index.
    int
    hashCode()
     
    boolean
    hasUnknownDimension()
    Returns whether one or more dimensions of this Shape have an unknown size.
    Shape
    head()
    Returns a 1-dimensional Shape with first dimension matching the first dimension of this Shape.
    static boolean
    isCompatible(long dim, long otherDim)
    Test to see if two shape dimensions are compatible.
    boolean
    isCompatibleWith(Shape shape)
    Determines whether another shape is compatible with this one.
    boolean
    isMatrix()
    Returns whether this Shape is the shape of a matrix
    boolean
    isScalar()
    Returns whether this Shape represents a scalar.
    boolean
    isUnknown()
    Returns whether the number of dimensions of this Shape is unknown.
    boolean
    isVector()
    Returns whether this Shape is the shape of a vector.
    int
    numDimensions()
    Returns the number of dimensions of this Shape.
    static Shape
    of(long... dimensionSizes)
    Create a Shape representing a scalar or an N-dimensional value.
    Shape
    prepend(long firstDimension)
    Returns a new Shape, with a new first dimension added.
    Shape
    prepend(Shape other)
    Returns a new Shape, with another Shape's dimensions prepended.
    static Shape
    scalar()
    Creates a Shape representing a scalar value.
    long
    size()
    Returns the total number of elements a Tensor with this Shape would have.
    long
    size(int i)
    Deprecated.
    Renamed to get(int).
    Shape
    subShape(int begin, int end)
    Return a end - begin dimensional shape with dimensions matching this Shape from begin to end.
    Shape
    tail()
    Returns a new Shape, with this Shape's first dimension removed.
    Shape
    take(int n)
    Returns an n-dimensional Shape with the dimensions matching the first n dimensions of this shape
    Shape
    takeLast(int n)
    Returns an n-dimensional Shape with the dimensions matching the last n dimensions of this Shape.
    List<Long>
    toListOrNull()
    Returns a defensive copy of the this Shape's axes.
    String
    toString()
    Succinct description of the Shape meant for debugging.
    static Shape
    unknown()
    Creates a Shape representing an unknown number of dimensions.

    Methods inherited from class Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Field Details

    • UNKNOWN_SIZE

      public static long UNKNOWN_SIZE
      The size of an unknown axis or the total unknown size for an unknown Shape.

  • Method Details

    • unknown

      public static Shape unknown()
      Creates a Shape representing an unknown number of dimensions.
      Returns:
      A Shape for which isUnknown() is true, never null.

    • scalar

      public static Shape scalar()
      Creates a Shape representing a scalar value.
      Returns:
      A Shape without dimensions for which isScalar() is true, never null.

    • of

      public static Shape of(long... dimensionSizes)
      Create a Shape representing a scalar or an N-dimensional value.

      Creates a Shape representing a scalar or an N-dimensional value (N being at least 1), with the provided size for each dimension. A -1 indicates that the size of the corresponding dimension is unknown. If no sizes are provided, a Shape representing a scalar is created. For example: 

      // A 2-element vector.
Shape vector = Shape.of(2);

// A 2x3 matrix.
Shape matrix = Shape.of(2, 3);

// A matrix with 4 columns but an unknown number of rows.
// This is typically used to indicate the shape of tensors that represent
// a variable-sized batch of values. The Shape below might represent a
// variable-sized batch of 4-element vectors.
Shape batch = Shape.of(-1, 4);

// A scalar. For readability, you should prefer calling Shape.scalar()
Shape scalar = Shape.of()
      Parameters:
      dimensionSizes - number of elements in each dimension of this shape, if any, or UNKNOWN_SIZE if unknown.
      Returns:
      a new shape

    • size

      public long size()
      Returns the total number of elements a Tensor with this Shape would have.

      If isUnknown() is true or hasUnknownDimension() is true, UNKNOWN_SIZE is returned.

      Returns:
      The total number of elements a Tensor with this shape would have if it can be calculated, else UNKNOWN_SIZE.

    • size

      @Deprecated public long size(int i)
      Deprecated.
      Renamed to get(int).
      The size of the dimension with the given index.

      If isUnknown() is true or the size of the dimension with the given index has an unknown size, UNKNOWN_SIZE is returned.

      Parameters:
      i - the index of the dimension to get the size for. If this Shape has a known number of dimensions, it must be < numDimensions(). The index may be negative, in which case the position is counted from the end of the shape. E.g.: size(-1) returns the size of the last dimension, size(-2) the size of the second to last dimension etc.
      Returns:
      The size of the dimension with the given index if known, UNKNOWN_SIZE otherwise.

    • get

      public long get(int i)
      The size of the dimension with the given index.

      If isUnknown() is true or the size of the dimension with the given index has an unknown size, UNKNOWN_SIZE is returned.

      Parameters:
      i - the index of the dimension to get the size for. If this Shape has a known number of dimensions, it must be < numDimensions(). The index may be negative, in which case the position is counted from the end of the shape. E.g.: size(-1) returns the size of the last dimension, size(-2) the size of the second to last dimension etc.
      Returns:
      The size of the dimension with the given index if known, UNKNOWN_SIZE otherwise.

    • numDimensions

      public int numDimensions()
      Returns the number of dimensions of this Shape. -1 if unknown, 0 for a scalar, 1 for a vector, 2 for a matrix etc.

    • hasUnknownDimension

      public boolean hasUnknownDimension()
      Returns whether one or more dimensions of this Shape have an unknown size.

    • isScalar

      public boolean isScalar()
      Returns whether this Shape represents a scalar.

    • isVector

      public boolean isVector()
      Returns whether this Shape is the shape of a vector.

    • isMatrix

      public boolean isMatrix()
      Returns whether this Shape is the shape of a matrix

    • isUnknown

      public boolean isUnknown()
      Returns whether the number of dimensions of this Shape is unknown.

    • asArray

      public long[] asArray()
      Returns a defensive copy of the this Shape's axes. Changes to the returned array to not change this Shape's state. Returns null if isUnknown() is true.

    • toListOrNull

      public List<Long> toListOrNull()
      Returns a defensive copy of the this Shape's axes. Changes to the returned list do not change this Shape's state. Returns null if isUnknown() is true.

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • equals

      public boolean equals(Object obj)
      Equals implementation for Shapes. Two Shapes are considered equal iff:

      • the number of dimensions is defined and equal for both
      • the size of each dimension is defined and equal for both

      If either Shape has unknown dimensions (even if they are the same in both) or if either shape has an unknown number of dimensions (even if both return true for isUnknown()), they are not considered equal! However, a shape will always equal itself, even if it is unknown or contains unknown dimensions.

      Overrides:
      equals in class Object

    • toString

      public String toString()
      Succinct description of the Shape meant for debugging.
      Overrides:
      toString in class Object

    • head

      public Shape head()
      Returns a 1-dimensional Shape with first dimension matching the first dimension of this Shape.

    • take

      public Shape take(int n)
      Returns an n-dimensional Shape with the dimensions matching the first n dimensions of this shape
      Parameters:
      n - the number of leading dimensions to get, must be <= than numDimensions()
      Returns:
      an n-dimensional Shape with the first n dimensions matching the first n dimensions of this Shape

    • tail

      public Shape tail()
      Returns a new Shape, with this Shape's first dimension removed.

    • takeLast

      public Shape takeLast(int n)
      Returns an n-dimensional Shape with the dimensions matching the last n dimensions of this Shape.
      Parameters:
      n - the number of trailing dimensions to get, must be <= than numDimensions()
      Returns:
      an n-dimensional shape with the dimensions matching the last n dimensions of this Shape, never null

    • subShape

      public Shape subShape(int begin, int end)
      Return a end - begin dimensional shape with dimensions matching this Shape from begin to end.
      Parameters:
      begin - Where to start the sub-shape.
      end - Where to end the sub-shape, exclusive.
      Returns:
      the sub-shape bounded by begin and end.

    • prepend

      public Shape prepend(long firstDimension)
      Returns a new Shape, with a new first dimension added. In order for this call to succeed, isUnknown() must be false.
      Parameters:
      firstDimension - the dimension to prepend
      Returns:
      a new shape with the given dimension first, followed by this Shape's dimensions, never null

    • append

      public Shape append(long lastDimension)
      Returns a new Shape, with a new last dimension added. In order for this call to succeed, isUnknown() must be false.
      Parameters:
      lastDimension - the dimension to append
      Returns:
      a new Shape with this Shape's dimensions followed by the given dimension, never null

    • prepend

      public Shape prepend(Shape other)
      Returns a new Shape, with another Shape's dimensions prepended. For both this Shape and the other Shape, isUnknown() must return false. E.g. Shape.of(3,4).prepend(Shape.of(1,2)) => Shape.of(1,2,3,4)
      Parameters:
      other - another Shape, must not be null, must not be unknown
      Returns:
      A new Shape consisting of the given Shape's dimensions followed by this Shape's dimensions, never null

    • append

      public Shape append(Shape other)
      Returns a new Shape, with another Shapes' dimensions appended. For both this Shape and the other Shape, isUnknown() must return false. E.g. @code Shape.of(3,4).append(Shape.of(1,2)) => Shape.of(3,4,1,2) }
      Parameters:
      other - another Shape, must not be null, must not be unknown
      Returns:
      A new Shape consisting of this Shape's dimensions followed by the given Shape's dimensions

    • isCompatibleWith

      public boolean isCompatibleWith(Shape shape)
      Determines whether another shape is compatible with this one.

      Two possibly-partially-defined shapes are compatible if there exists a fully-defined shape that both shapes can represent. Thus, compatibility allows the shape inference code to reason about partially-defined shapes. For example:

      • Shape.unknown() is compatible with all shapes.
      • Shape(UNKNOWN_SIZE, UNKNOWN_SIZE) is compatible with all two-dimensional shapes, such as Shape(32, 784), and also Shape.unknown(). It is not compatible with, for example, Shape(UNKNOWN_SIZE) or Shape(UNKNOWN_SIZE, UNKNOWN_SIZE, UNKNOWN_SIZE).
      • Shape(32, UNKNOWN_SIZE) is compatible with all two-dimensional shapes with size 32 in the 0th dimension, and also Shape(UNKNOWN_SIZE, UNKNOWN_SIZE) and Shape.unknown(). It is not compatible with, for example, Shape(32) , Shape(32, UNKNOWN_SIZE, 1) or Shape(64, UNKNOWN_SIZE).
      • Shape(32, 784) is compatible with itself, and also Shape(32, UNKNOWN_SIZE), Shape(UNKNOWN_SIZE, 784), Shape(UNKNOWN_SIZE, UNKNOWN_SIZE) and Shape.unknown(). It is not compatible with, for example, Shape(32, 1, 784) or Shape(UNKNOWN_SIZE) .

      The compatibility relation is reflexive and symmetric, but not transitive. For example, Shape(32, 784) is compatible with Shape.unknown(), and Shape.unknown() is compatible with Shape(4, 4), but Shape(32, 784) is not compatible with Shape(4, 4).

      Compatibility is not the same as broadcasting. Compatible shapes must have the same number of dimensions and for each dimension pair, one dimension has to equal the other dimensions or at least one of the dimensions in the pair has to be UNKNOWN_SIZE.

      Broadcasting allows different dimensions, but paired dimensions have to either be equal, or one dimension must be 1. If one shape has less dimensions than another shape, the smaller shape is "stretched" with dimensions of 1.

      Parameters:
      shape - The other shape
      Returns:
      true, if the two shapes are compatible.

    • isCompatible

      public static boolean isCompatible(long dim, long otherDim)
      Test to see if two shape dimensions are compatible.

      The dimensions are compatible if either dimension is Shape.UNKNOWN_SIZE or both dimensions are equal

      Parameters:
      dim - the first dimension
      otherDim - the second dimension
      Returns:
      true, if both dimensions are compatible