A tf.Tensor
represents a multidimensional array of elements.
All elements are of a single known data type.
When writing a TensorFlow program, the main object that is
manipulated and passed around is the tf.Tensor
.
A tf.Tensor
has the following properties:
- a single data type (float32, int32, or string, for example)
- a shape
TensorFlow supports eager execution and graph execution. In eager execution, operations are evaluated immediately. In graph execution, a computational graph is constructed for later evaluation.
TensorFlow defaults to eager execution. In the example below, the matrix multiplication results are calculated immediately.
>>>
# Compute some values using a Tensor
>>>
c
=
tf
.
constant
([[
1.0
,
2.0
],
[
3.0
,
4.0
]])
>>>
d
=
tf
.
constant
([[
1.0
,
1.0
],
[
0.0
,
1.0
]])
>>>
e
=
tf
.
matmul
(
c
,
d
)
>>>
print
(
e
)
tf
.
Tensor
(
[[
1.
3.
]
[
3.
7.
]],
shape
=
(
2
,
2
),
dtype
=
float32
)
Note that during eager execution, you may discover your Tensors
are actually
of type EagerTensor
. This is an internal detail, but it does give you
access to a useful function, numpy
:
>>>
type
(
e
)
< class
'
...
ops
.
EagerTensor
'
>
>>>
print
(
e
.
numpy
())
[[
1
.
3
.]
[
3
.
7
.]]
In TensorFlow, tf.function
s are a common way to define graph execution.
A Tensor's shape (that is, the rank of the Tensor and the size of
each dimension) may not always be fully known. In tf.function
definitions, the shape may only be partially known.
Most operations produce tensors of fully-known shapes if the shapes of their inputs are also fully known, but in some cases it's only possible to find the shape of a tensor at execution time.
A number of specialized tensors are available: see tf.Variable
, tf.constant
, tf.placeholder
, tf.sparse.SparseTensor
, and tf.RaggedTensor
.
a
=
np
.
array
([
1
,
2
,
3
])
b
=
tf
.
constant
(
a
)
a
[
0
]
=
4
print
(
b
)
# tf.Tensor([4 2 3], shape=(3,), dtype=int64)
For more on Tensors, see the guide .
Attributes
>>>
t
=
tf
.
constant
([
1
,
2
,
3
,
4
,
5
])
>>>
t
.
shape
TensorShape
([
5
])
tf.Tensor.shape
is equivalent to tf.Tensor.get_shape()
.
In a tf.function
or when building a model using tf.keras.Input
, they return the build-time shape of the
tensor, which may be partially unknown.
A tf.TensorShape
is not a tensor. Use tf.shape(t)
to get a tensor
containing the shape, calculated at runtime.
See tf.Tensor.get_shape()
, and tf.TensorShape
for details and examples.
Methods
eval
eval
(
feed_dict
=
None
,
session
=
None
)
Evaluates this tensor in a Session
.
Calling this method will execute all preceding operations that produce the inputs needed for the operation that produces this tensor.
N.B.
Before invoking Tensor.eval()
, its graph must have been
launched in a session, and either a default session must be
available, or session
must be specified explicitly.
feed_dict
Tensor
objects to feed values. See tf.Session.run
for a description of the valid feed values.session
Session
to be used to evaluate this tensor. If
none, the default session will be used.
experimental_ref
experimental_ref
()
DEPRECATED FUNCTION
get_shape
get_shape
()
->
meridian
.
backend
.
TensorShape
Returns a tf.TensorShape
that represents the shape of this tensor.
In eager execution the shape is always fully-known.
>>>
a
=
tf
.
constant
([[
1.0
,
2.0
,
3.0
],
[
4.0
,
5.0
,
6.0
]])
>>>
print
(
a
.
shape
)
(
2
,
3
)
tf.Tensor.get_shape()
is equivalent to tf.Tensor.shape
.
When executing in a tf.function
or building a model using tf.keras.Input
, Tensor.shape
may return a partial shape (including None
for unknown dimensions). See tf.TensorShape
for more details.
>>> inputs = tf.keras.Input(shape = [10])
>>> # Unknown batch size
>>> print(inputs.shape)
(None, 10)
The shape is computed using shape inference functions that are
registered for each tf.Operation
.
The returned tf.TensorShape
is determined at build
time, without
executing the underlying kernel. It is not a tf.Tensor
. If you need a
shape tensor
, either convert the tf.TensorShape
to a tf.constant
, or
use the tf.shape(tensor)
function, which returns the tensor's shape at execution
time.
This is useful for debugging and providing early errors. For
example, when tracing a tf.function
, no ops are being executed, shapes
may be unknown (See the Concrete Functions
Guide
for details).
>>>
@tf.function
...
def
my_matmul
(
a
,
b
)
:
...
result
=
a
@b
...
# the `print` executes during tracing.
...
print
(
"Result shape: "
,
result
.
shape
)
...
return
result
The shape inference functions propagate shapes to the extent possible:
>>> f = my_matmul.get_concrete_function( ...
tf.TensorSpec([None,3]), ...
tf.TensorSpec([3,5]))
Result shape: (None, 5)
Tracing may fail if a shape missmatch can be detected:
>>> cf = my_matmul.get_concrete_function( ...
tf.TensorSpec([None,3]), ...
tf.TensorSpec([4,5]))
Traceback (most recent call last):
...
ValueError: Dimensions must be equal, but are 3 and 4 for 'matmul' (op:
'MatMul') with input shapes: [?,3], [4,5].
In some cases, the inferred shape may have unknown dimensions. If
the caller has additional information about the values of these
dimensions, tf.ensure_shape
or Tensor.set_shape()
can be used to augment
the inferred shape.
>>>
@tf.function
...
def
my_fun
(
a
)
:
...
a
=
tf
.
ensure_shape
(
a
,
[
5
,
5
]
)
...
# the `print` executes during tracing.
...
print
(
"Result shape: "
,
a
.
shape
)
...
return
a
>>> cf = my_fun.get_concrete_function( ...
tf.TensorSpec([None, None]))
Result shape: (5, 5)
tf.TensorShape
representing the shape of this tensor. ref
ref
()
Returns a hashable reference object to this Tensor.
The primary use case for this API is to put tensors in a set/dictionary.
We can't put tensors in a set/dictionary as tensor.__hash__()
is no longer
available starting Tensorflow 2.0.
The following will raise an exception starting 2.0
>>> x = tf.constant(5)
>>> y = tf.constant(10)
>>> z = tf.constant(10)
>>> tensor_set = {x, y, z}
Traceback (most recent call last):
...
TypeError: Tensor is unhashable. Instead, use tensor.ref() as the key.
>>> tensor_dict = {x: 'five', y: 'ten'}
Traceback (most recent call last):
...
TypeError: Tensor is unhashable. Instead, use tensor.ref() as the key.
Instead, we can use tensor.ref()
.
>>> tensor_set = {x.ref(), y.ref(), z.ref()}
>>> x.ref() in tensor_set
True
>>> tensor_dict = {x.ref(): 'five', y.ref(): 'ten', z.ref(): 'ten'}
>>> tensor_dict[y.ref()]
'ten'
Also, the reference object provides .deref()
function that returns the
original Tensor.
>>> x = tf.constant(5)
>>> x.ref().deref()
<tf.Tensor: shape=(), dtype=int32, numpy=5>
set_shape
set_shape
(
shape
)
Updates the shape of this tensor.
With eager execution this operates as a shape assertion. Here the shapes match:
>>>
t
=
tf
.
constant
([[
1
,
2
,
3
]])
>>>
t
.
set_shape
([
1
,
3
])
Passing a None
in the new shape allows any value for that axis:
>>> t.set_shape([1,None])
An error is raised if an incompatible shape is passed.
>>> t.set_shape([1,5])
Traceback (most recent call last):
...
ValueError: Tensor's shape (1, 3) is not compatible with supplied
shape [1, 5]
When executing in a tf.function
, or building a model using tf.keras.Input
, Tensor.set_shape
will merge
the given shape
with
the current shape of this tensor, and set the tensor's shape to the
merged value (see tf.TensorShape.merge_with
for details):
>>> t = tf.keras.Input(shape=[None, None, 3])
>>> print(t.shape)
(None, None, None, 3)
Dimensions set to None
are not updated:
>>> t.set_shape([None, 224, 224, None])
>>> print(t.shape)
(None, 224, 224, 3)
The main use case for this is to provide additional shape information that cannot be inferred from the graph alone.
For example if you know all the images in a dataset have shape [28,28,3] you
can set it with tf.set_shape
:
>>>
@tf.function
...
def
load_image
(
filename
)
:
...
raw
=
tf
.
io
.
read_file
(
filename
)
...
image
=
tf
.
image
.
decode_png
(
raw
,
channels
=
3
)
...
# the `print` executes during tracing.
...
print
(
"Initial shape: "
,
image
.
shape
)
...
image
.
set
_shape
(
[
28
,
28
,
3
]
)
...
print
(
"Final shape: "
,
image
.
shape
)
...
return
image
Trace the function, see the Concrete Functions Guide for details.
>>>
cf
=
load_image
.
get_concrete_function
(
...
tf
.
TensorSpec
([],
dtype
=
tf
.
string
))
Initial
shape
:
(
None
,
None
,
3
)
Final
shape
:
(
28
,
28
,
3
)
Similarly the tf.io.parse_tensor
function could return a tensor with
any shape, even the tf.rank
is unknown. If you know that all your
serialized tensors will be 2d, set it with set_shape
:
>>>
@tf.function
...
def
my_parse
(
string_tensor
)
:
...
result
=
tf
.
io
.
parse_tensor
(
string_tensor
,
out_type
=
tf
.
float32
)
...
# the `print` executes during tracing.
...
print
(
"Initial shape: "
,
result
.
shape
)
...
result
.
set
_shape
(
[
None
,
None
]
)
...
print
(
"Final shape: "
,
result
.
shape
)
...
return
result
Trace the function
>>>
concrete_parse
=
my_parse
.
get_concrete_function
(
...
tf
.
TensorSpec
([],
dtype
=
tf
.
string
))
Initial
shape
:
< unknown
> Final
shape
:
(
None
,
None
)
Make sure it works:
>>>
t
=
tf
.
ones
([
5
,
3
],
dtype
=
tf
.
float32
)
>>>
serialized
=
tf
.
io
.
serialize_tensor
(
t
)
>>>
print
(
serialized
.
dtype
)
< dtype
:
'
string
'
>
>>>
print
(
serialized
.
shape
)
()
>>>
t2
=
concrete_parse
(
serialized
)
>>>
print
(
t2
.
shape
)
(
5
,
3
)
>>>
#
Serialize
a
rank
-
3
tensor
>>>
t
=
tf
.
ones
([
5
,
5
,
5
],
dtype
=
tf
.
float32
)
>>>
serialized
=
tf
.
io
.
serialize_tensor
(
t
)
>>>
#
The
function
still
runs
,
even
though
it
`
set_shape
([
None
,
None
])
`
>>>
t2
=
concrete_parse
(
serialized
)
>>>
print
(
t2
.
shape
)
(
5
,
5
,
5
)
shape
TensorShape
representing the shape of this tensor, a TensorShapeProto
, a list, a tuple, or None.
ValueError
shape
is not compatible with the current shape of
this tensor. __abs__
__abs__
(
name
=
None
)
__add__
__add__
(
y
)
__and__
__and__
(
y
)
__array__
__array__
(
dtype
=
None
)
__bool__
__bool__
()
Dummy method to prevent a tensor from being used as a Python bool
.
This overload raises a TypeError
when the user inadvertently
treats a Tensor
as a boolean (most commonly in an if
or while
statement), in code that was not converted by AutoGraph. For example:
if
tf
.
constant
(
True
):
# Will raise.
# ...
if
tf
.
constant
(
5
)
< tf
.
constant
(
7
):
# Will raise.
# ...
TypeError
. __div__
__div__
(
y
)
__eq__
__eq__
(
other
)
__floordiv__
__floordiv__
(
y
)
__ge__
__ge__
(
y
:
Annotated
[
Any
,
TV_GreaterEqual_T
],
name
=
None
)
->
Annotated
[
Any
,
_atypes
.
Bool
]
Returns the truth value of (x >= y) element-wise.
NOTE
: math.greater_equal
supports broadcasting. More about broadcasting here
Example:
x
=
tf
.
constant
([
5
,
4
,
6
,
7
])
y
=
tf
.
constant
([
5
,
2
,
5
,
10
])
tf
.
math
.
greater_equal
(
x
,
y
)
==
> [
True
,
True
,
True
,
False
]
x
=
tf
.
constant
([
5
,
4
,
6
,
7
])
y
=
tf
.
constant
([
5
])
tf
.
math
.
greater_equal
(
x
,
y
)
==
> [
True
,
False
,
True
,
True
]
x
Tensor
. Must be one of the following types: float32
, float64
, int32
, uint8
, int16
, int8
, int64
, bfloat16
, uint16
, half
, uint32
, uint64
.y
Tensor
. Must have the same type as x
.name
Tensor
of type bool
. __getitem__
__getitem__
(
slice_spec
,
var
=
None
)
Overload for Tensor. getitem.
This operation extracts the specified region from the tensor. The notation is similar to NumPy with the restriction that currently only support basic indexing. That means that using a non-scalar tensor as input is not currently allowed.
Some useful examples:
# Strip leading and trailing 2 elements
foo
=
tf
.
constant
([
1
,
2
,
3
,
4
,
5
,
6
])
print
(
foo
[
2
:
-
2
])
# => [3,4]
# Skip every other row and reverse the order of the columns
foo
=
tf
.
constant
([[
1
,
2
,
3
],
[
4
,
5
,
6
],
[
7
,
8
,
9
]])
print
(
foo
[::
2
,::
-
1
])
# => [[3,2,1], [9,8,7]]
# Use scalar tensors as indices on both dimensions
print
(
foo
[
tf
.
constant
(
0
),
tf
.
constant
(
2
)])
# => 3
# Insert another dimension
foo
=
tf
.
constant
([[
1
,
2
,
3
],
[
4
,
5
,
6
],
[
7
,
8
,
9
]])
print
(
foo
[
tf
.
newaxis
,
:,
:])
# => [[[1,2,3], [4,5,6], [7,8,9]]]
print
(
foo
[:,
tf
.
newaxis
,
:])
# => [[[1,2,3]], [[4,5,6]], [[7,8,9]]]
print
(
foo
[:,
:,
tf
.
newaxis
])
# => [[[1],[2],[3]], [[4],[5],[6]],
[[
7
],[
8
],[
9
]]]
# Ellipses (3 equivalent operations)
foo
=
tf
.
constant
([[
1
,
2
,
3
],
[
4
,
5
,
6
],
[
7
,
8
,
9
]])
print
(
foo
[
tf
.
newaxis
,
:,
:])
# => [[[1,2,3], [4,5,6], [7,8,9]]]
print
(
foo
[
tf
.
newaxis
,
...
])
# => [[[1,2,3], [4,5,6], [7,8,9]]]
print
(
foo
[
tf
.
newaxis
])
# => [[[1,2,3], [4,5,6], [7,8,9]]]
# Masks
foo
=
tf
.
constant
([[
1
,
2
,
3
],
[
4
,
5
,
6
],
[
7
,
8
,
9
]])
print
(
foo
[
foo
> 2
])
# => [3, 4, 5, 6, 7, 8, 9]
tf.newaxis
is None
as in NumPy.
- An implicit ellipsis is placed at the end of the slice_spec
- NumPy advanced indexing is currently not supported.
Tensor. getitem
to allow it to handle
custom composite tensors & other custom objects. The API symbol is not intended to be called by users directly and does appear in TensorFlow's generated documentation.
tensor
slice_spec
var
ValueError
TypeError
__gt__
__gt__
(
y
:
Annotated
[
Any
,
TV_Greater_T
],
name
=
None
)
->
Annotated
[
Any
,
_atypes
.
Bool
]
Returns the truth value of (x > y) element-wise.
NOTE
: math.greater
supports broadcasting. More about broadcasting here
Example:
x
=
tf
.
constant
([
5
,
4
,
6
])
y
=
tf
.
constant
([
5
,
2
,
5
])
tf
.
math
.
greater
(
x
,
y
)
==
> [
False
,
True
,
True
]
x
=
tf
.
constant
([
5
,
4
,
6
])
y
=
tf
.
constant
([
5
])
tf
.
math
.
greater
(
x
,
y
)
==
> [
False
,
False
,
True
]
x
Tensor
. Must be one of the following types: float32
, float64
, int32
, uint8
, int16
, int8
, int64
, bfloat16
, uint16
, half
, uint32
, uint64
.y
Tensor
. Must have the same type as x
.name
Tensor
of type bool
. __invert__
__invert__
(
name
=
None
)
__iter__
__iter__
()
__le__
__le__
(
y
:
Annotated
[
Any
,
TV_LessEqual_T
],
name
=
None
)
->
Annotated
[
Any
,
_atypes
.
Bool
]
Returns the truth value of (x <= y) element-wise.
NOTE
: math.less_equal
supports broadcasting. More about broadcasting here
Example:
x
=
tf
.
constant
([
5
,
4
,
6
])
y
=
tf
.
constant
([
5
])
tf
.
math
.
less_equal
(
x
,
y
)
==
> [
True
,
True
,
False
]
x
=
tf
.
constant
([
5
,
4
,
6
])
y
=
tf
.
constant
([
5
,
6
,
6
])
tf
.
math
.
less_equal
(
x
,
y
)
==
> [
True
,
True
,
True
]
x
Tensor
. Must be one of the following types: float32
, float64
, int32
, uint8
, int16
, int8
, int64
, bfloat16
, uint16
, half
, uint32
, uint64
.y
Tensor
. Must have the same type as x
.name
Tensor
of type bool
. __len__
__len__
()
__lt__
__lt__
(
y
:
Annotated
[
Any
,
TV_Less_T
],
name
=
None
)
->
Annotated
[
Any
,
_atypes
.
Bool
]
Returns the truth value of (x < y) element-wise.
NOTE
: math.less
supports broadcasting. More about broadcasting here
Example:
x
=
tf
.
constant
([
5
,
4
,
6
])
y
=
tf
.
constant
([
5
])
tf
.
math
.
less
(
x
,
y
)
==
> [
False
,
True
,
False
]
x
=
tf
.
constant
([
5
,
4
,
6
])
y
=
tf
.
constant
([
5
,
6
,
7
])
tf
.
math
.
less
(
x
,
y
)
==
> [
False
,
True
,
True
]
x
Tensor
. Must be one of the following types: float32
, float64
, int32
, uint8
, int16
, int8
, int64
, bfloat16
, uint16
, half
, uint32
, uint64
.y
Tensor
. Must have the same type as x
.name
Tensor
of type bool
. __matmul__
__matmul__
(
y
)
__mod__
__mod__
(
y
)
__mul__
__mul__
(
y
)
__ne__
__ne__
(
other
)
__neg__
__neg__
(
name
=
None
)
->
Annotated
[
Any
,
TV_Neg_T
]
Computes numerical negative value element-wise.
I.e., \(y = -x\).
x
Tensor
. Must be one of the following types: bfloat16
, half
, float32
, float64
, int8
, int16
, int32
, int64
, complex64
, complex128
.name
Tensor
. Has the same type as x
. If x
is a SparseTensor
, returns SparseTensor(x.indices, tf.math.negative(x.values, ...), x.dense_shape)
__nonzero__
__nonzero__
()
Dummy method to prevent a tensor from being used as a Python bool
.
This is the Python 2.x counterpart to __bool__()
above.
TypeError
. __or__
__or__
(
y
)
__pow__
__pow__
(
y
)
__radd__
__radd__
(
x
)
__rand__
__rand__
(
x
)
__rdiv__
__rdiv__
(
x
)
__rfloordiv__
__rfloordiv__
(
x
)
__rmatmul__
__rmatmul__
(
x
)
__rmod__
__rmod__
(
x
)
__rmul__
__rmul__
(
x
)
__ror__
__ror__
(
x
)
__rpow__
__rpow__
(
x
)
__rsub__
__rsub__
(
x
)
__rtruediv__
__rtruediv__
(
x
)
__rxor__
__rxor__
(
x
)
__sub__
__sub__
(
y
)
__truediv__
__truediv__
(
y
)
__xor__
__xor__
(
y
)
Class Variables
{
'__abs__',
'__add__',
'__and__',
'__div__',
'__eq__',
'__floordiv__',
'__ge__',
'__getitem__',
'__gt__',
'__invert__',
'__le__',
'__lt__',
'__matmul__',
'__mod__',
'__mul__',
'__ne__',
'__neg__',
'__or__',
'__pow__',
'__radd__',
'__rand__',
'__rdiv__',
'__rfloordiv__',
'__rmatmul__',
'__rmod__',
'__rmul__',
'__ror__',
'__rpow__',
'__rsub__',
'__rtruediv__',
'__rxor__',
'__sub__',
'__truediv__',
'__xor__'
}
