tf.TensorShape

Represents the shape of a Tensor.

Inherits From: TraceType

tf.TensorShape(
    dims
)

Used in the notebooks

t = tf.constant([[1,2,3],[4,5,6]])
t.shape
TensorShape([2, 3])

TensorShape is the static shape representation of a Tensor. During eager execution a Tensor always has a fully specified shape but when tracing a tf.function it may be one of the following:

• Fully-known shape: has a known number of dimensions and a known size for each dimension. e.g. TensorShape([16, 256])
• Partially-known shape: has a known number of dimensions, and an unknown size for one or more dimension. e.g. TensorShape([None, 256])
• Unknown shape: has an unknown number of dimensions, and an unknown size in all dimensions. e.g. TensorShape(None)

During function tracing t.shape will return a TensorShape object representing the shape of Tensor as it is known during tracing. This static representation will be partially defined in cases where the exact shape depends on the values within the tensors. To get the dynamic representation, please use tf.shape(t) which will return Tensor representing the fully defined shape of t. This way, you can express logic that manipulates the shapes of tensors by building other tensors that depend on the dynamic shape of t.

Note: tf.RaggedTensor.shape also returns a tf.TensorShape, the lengths of any ragged dimensions are unknown (None).

For example, this function prints the TensorShape' (t.shape), when you trace the function, and returns a tensor <a href="../tf/shape"><code>tf.shape(t)</code></a> for given inputt`:

@tf.function
def get_dynamic_shape(t):
  print("tracing...")
  print(f"static shape is {t.shape}")
  return tf.shape(t)

Just calling the function traces it with a fully-specified static shape:

result = get_dynamic_shape(tf.constant([[1, 1, 1], [0, 0, 0]]))
tracing...
static shape is (2, 3)
result.numpy()
array([2, 3], dtype=int32)

But tf.function can also trace the function with a partially specified (or even unspecified) shape:

cf1 = get_dynamic_shape.get_concrete_function(tf.TensorSpec(
                                              shape=[None, 2]))
tracing...
static shape is (None, 2)
cf1(tf.constant([[1., 0],[1, 0],[1, 0]])).numpy()
array([3, 2], dtype=int32)

cf2 = get_dynamic_shape.get_concrete_function(tf.TensorSpec(shape=None))
tracing...
static shape is <unknown>
cf2(tf.constant([[[[[1., 0]]]]])).numpy()
array([1, 1, 1, 1, 2], dtype=int32)

If a tensor is produced by an operation of type "Foo", its shape may be inferred if there is a registered shape function for "Foo". See Shape functions for details of shape functions and how to register them. Alternatively, you may set the shape explicitly using tf.Tensor.ensure_shape.

Methods

as_list

View source

as_list()

Returns a list of integers or None for each dimension.

as_proto

View source

as_proto()

Returns this shape as a TensorShapeProto.

assert_has_rank

View source

assert_has_rank(
    rank
)

Raises an exception if self is not compatible with the given rank.

assert_is_compatible_with

View source

assert_is_compatible_with(
    other
)

Raises exception if self and other do not represent the same shape.

This method can be used to assert that there exists a shape that both self and other represent.

assert_is_fully_defined

View source

assert_is_fully_defined()

Raises an exception if self is not fully defined in every dimension.

assert_same_rank

View source

assert_same_rank(
    other
)

Raises an exception if self and other do not have compatible ranks.

concatenate

View source

concatenate(
    other
)

Returns the concatenation of the dimension in self and other.

Note: If either self or other is completely unknown, concatenation will discard information about the other shape. In future, we might support concatenation that preserves this information for use with slicing.

experimental_as_proto

View source

experimental_as_proto() -> tensor_shape_pb2.TensorShapeProto

Returns a proto representation of the TensorShape instance.

experimental_from_proto

View source

@classmethod
experimental_from_proto(
    proto: tensor_shape_pb2.TensorShapeProto
) -> 'TensorShape'

Returns a TensorShape instance based on the serialized proto.

experimental_type_proto

View source

@classmethod
experimental_type_proto() -> Type[tensor_shape_pb2.TensorShapeProto]

Returns the type of proto associated with TensorShape serialization.

is_compatible_with

View source

is_compatible_with(
    other
)

Returns True iff self is compatible with other.

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:

• TensorShape(None) is compatible with all shapes.

• TensorShape([None, None]) is compatible with all two-dimensional shapes, such as TensorShape([32, 784]), and also TensorShape(None). It is not compatible with, for example, TensorShape([None]) or TensorShape([None, None, None]).

• TensorShape([32, None]) is compatible with all two-dimensional shapes with size 32 in the 0th dimension, and also TensorShape([None, None]) and TensorShape(None). It is not compatible with, for example, TensorShape([32]), TensorShape([32, None, 1]) or TensorShape([64, None]).

• TensorShape([32, 784]) is compatible with itself, and also TensorShape([32, None]), TensorShape([None, 784]), TensorShape([None, None]) and TensorShape(None). It is not compatible with, for example, TensorShape([32, 1, 784]) or TensorShape([None]).

The compatibility relation is reflexive and symmetric, but not transitive. For example, TensorShape([32, 784]) is compatible with TensorShape(None), and TensorShape(None) is compatible with TensorShape([4, 4]), but TensorShape([32, 784]) is not compatible with TensorShape([4, 4]).

is_fully_defined

View source

is_fully_defined()

Returns True iff self is fully defined in every dimension.

is_subtype_of

View source

is_subtype_of(
    other: tf.types.experimental.TraceType
) -> bool

Returns True iff self is subtype of other.

Shape A is a subtype of shape B if shape B can successfully represent it:

• A TensorShape of any rank is a subtype of TensorShape(None).

• TensorShapes of equal ranks are covariant, i.e. TensorShape([A1, A2, ..]) is a subtype of TensorShape([B1, B2, ..]) iff An is a subtype of Bn.

  An is subtype of Bn iff An == Bn or Bn is None.

• TensorShapes of different defined ranks have no subtyping relation.

The subtyping relation is reflexive and transitive, but not symmetric.

Some examples:

• TensorShape([32, 784]) is a subtype of TensorShape(None), and TensorShape([4, 4]) is also a subtype of TensorShape(None) but TensorShape([32, 784]) and TensorShape([4, 4]) are not subtypes of each other.

• All two-dimensional shapes are subtypes of TensorShape([None, None]), such as TensorShape([32, 784]). There is no subtype relationship with, for example, TensorShape([None]) or TensorShape([None, None, None]).

• TensorShape([32, None]) is also a subtype of TensorShape([None, None]) and TensorShape(None). It is not a subtype of, for example, TensorShape([32]), TensorShape([32, None, 1]), TensorShape([64, None]) or TensorShape([None, 32]).

• TensorShape([32, 784]) is a subtype of itself, and also TensorShape([32, None]), TensorShape([None, 784]), TensorShape([None, None]) and TensorShape(None). It has no subtype relation with, for example, TensorShape([32, 1, 784]) or TensorShape([None]).

merge_with

View source

merge_with(
    other
)

Returns a TensorShape combining the information in self and other.

The dimensions in self and other are merged element-wise, according to the rules below:

Dimension(n).merge_with(Dimension(None)) == Dimension(n)
Dimension(None).merge_with(Dimension(n)) == Dimension(n)
Dimension(None).merge_with(Dimension(None)) == Dimension(None)
# raises ValueError for n != m
Dimension(n).merge_with(Dimension(m))

ts = tf.TensorShape([1,2]) ot1 = tf.TensorShape([1,2]) ts.merge_with(ot).as_list() [1,2]

ot2 = tf.TensorShape([1,None]) ts.merge_with(ot2).as_list() [1,2]

ot3 = tf.TensorShape([None, None]) ot3.merge_with(ot2).as_list() [1, None]

most_specific_common_supertype

View source

most_specific_common_supertype(
    others: Sequence[tf.types.experimental.TraceType]
) -> Optional['TensorShape']

Returns the most specific supertype TensorShape of self and others.

• TensorShape([None, 1]) is the most specific TensorShape supertyping both TensorShape([2, 1]) and TensorShape([5, 1]). Note that TensorShape(None) is also a supertype but it is not "most specific".

• TensorShape([1, 2, 3]) is the most specific TensorShape supertyping both TensorShape([1, 2, 3]) and TensorShape([1, 2, 3]). There are other less specific TensorShapes that supertype above mentioned TensorShapes, e.g. TensorShape([1, 2, None]), TensorShape(None).

  • TensorShape([None, None]) is the most specific TensorShape supertyping both TensorShape([2, None]) and TensorShape([None, 3]). As always, TensorShape(None) is also a supertype but not the most specific one.

  • TensorShape(None) is the only TensorShape supertyping both TensorShape([1, 2, 3]) and TensorShape([1, 2]). In general, any two shapes that have different ranks will only have TensorShape(None) as a common supertype.

  • TensorShape(None) is the only TensorShape supertyping both TensorShape([1, 2, 3]) and TensorShape(None). In general, the common supertype of any shape with TensorShape(None) is TensorShape(None).

most_specific_compatible_shape

View source

most_specific_compatible_shape(
    other
) -> 'TensorShape'

Returns the most specific TensorShape compatible with self and other.

• TensorShape([None, 1]) is the most specific TensorShape compatible with both TensorShape([2, 1]) and TensorShape([5, 1]). Note that TensorShape(None) is also compatible with above mentioned TensorShapes.

• TensorShape([1, 2, 3]) is the most specific TensorShape compatible with both TensorShape([1, 2, 3]) and TensorShape([1, 2, 3]). There are more less specific TensorShapes compatible with above mentioned TensorShapes, e.g. TensorShape([1, 2, None]), TensorShape(None).

num_elements

View source

num_elements()

Returns the total number of elements, or none for incomplete shapes.

with_rank

View source

with_rank(
    rank
)

Returns a shape based on self with the given rank.

This method promotes a completely unknown shape to one with a known rank.

with_rank_at_least

View source

with_rank_at_least(
    rank
)

Returns a shape based on self with at least the given rank.

with_rank_at_most

View source

with_rank_at_most(
    rank
)

Returns a shape based on self with at most the given rank.

__add__

View source

__add__(
    other
)

__bool__

View source

__bool__()

Returns True if this shape contains non-zero information.

__concat__

View source

__concat__(
    other
)

__eq__

View source

__eq__(
    other
)

Returns True if self is equivalent to other.

It first tries to convert other to TensorShape. TypeError is thrown when the conversion fails. Otherwise, it compares each element in the TensorShape dimensions.

• Two Fully known shapes, return True iff each element is equal.

>>> t_a = tf.TensorShape([1,2])
>>> a = [1, 2]
>>> t_b = tf.TensorShape([1,2])
>>> t_c = tf.TensorShape([1,2,3])
>>> t_a.__eq__(a)
True
>>> t_a.__eq__(t_b)
True
>>> t_a.__eq__(t_c)
False

• Two Partially-known shapes, return True iff each element is equal.

>>> p_a = tf.TensorShape([1,None])
>>> p_b = tf.TensorShape([1,None])
>>> p_c = tf.TensorShape([2,None])
>>> p_a.__eq__(p_b)
True
>>> t_a.__eq__(p_a)
False
>>> p_a.__eq__(p_c)
False

• Two Unknown shape, return True.

>>> unk_a = tf.TensorShape(None)
>>> unk_b = tf.TensorShape(None)
>>> unk_a.__eq__(unk_b)
True
>>> unk_a.__eq__(t_a)
False

__getitem__

View source

__getitem__(
    key
)

Returns the value of a dimension or a shape, depending on the key.

__iter__

View source

__iter__()

Returns self.dims if the rank is known, otherwise raises ValueError.

__len__

View source

__len__()

Returns the rank of this shape, or raises ValueError if unspecified.

__nonzero__

View source

__nonzero__()

Returns True if this shape contains non-zero information.

__radd__

View source

__radd__(
    other
)