tf.experimental.numpy: NumPy API on TensorFlow.
This module provides a subset of NumPy API, built on top of TensorFlow operations. APIs are based on and have been tested with NumPy 1.16 version.
The set of supported APIs may be expanded over time. Also future releases may change the baseline version of NumPy API being supported. A list of some systematic differences with NumPy is listed later in the "Differences with NumPy" section.
Getting Started
Please also see TensorFlow NumPy Guide.
In the code snippets below, we will assume that tf.experimental.numpy
is
imported as tnp
and NumPy is imported as np
print(tnp.ones([2,1]) + np.ones([1, 2]))
Types
The module provides an ndarray
class which wraps an immutable tf.Tensor
.
Additional functions are provided which accept array-like objects. Here
array-like objects include ndarrays
as defined by this module, as well as
tf.Tensor
, in addition to types accepted by NumPy.
A subset of NumPy dtypes are supported. Type promotion follows NumPy semantics.
print(tnp.ones([1, 2], dtype=tnp.int16) + tnp.ones([2, 1], dtype=tnp.uint8))
Array Interface
The ndarray
class implements the __array__
interface. This should allow
these objects to be passed into contexts that expect a NumPy or array-like
object (e.g. matplotlib).
np.sum(tnp.ones([1, 2]) + np.ones([2, 1]))
TF Interoperability
The TF-NumPy API calls can be interleaved with TensorFlow calls
without incurring Tensor data copies. This is true even if the ndarray
or
tf.Tensor
is placed on a non-CPU device.
In general, the expected behavior should be on par with that of code involving
tf.Tensor
and running stateless TensorFlow functions on them.
tnp.sum(tnp.ones([1, 2]) + tf.ones([2, 1]))
Note that the __array_priority__
is currently chosen to be lower than
tf.Tensor
. Hence the +
operator above returns a tf.Tensor
.
Additional examples of interoperability include:
- using
with tf.GradientTape()
scope to compute gradients through the TF-NumPy API calls. - using
tf.distribution.Strategy
scope for distributed execution - using
tf.vectorized_map()
for speeding up code using auto-vectorization
Device Support
Given that ndarray
and functions wrap TensorFlow constructs, the code will
have GPU and TPU support on par with TensorFlow. Device placement can be
controlled by using with tf.device
scopes. Note that these devices could
be local or remote.
with tf.device("GPU:0"):
x = tnp.ones([1, 2])
print(tf.convert_to_tensor(x).device)
Graph and Eager Modes
Eager mode execution should typically match NumPy semantics of executing
op-by-op. However the same code can be executed in graph mode, by putting it
inside a tf.function
. The function body can contain NumPy code, and the inputs
can be ndarray
as well.
@tf.function
def f(x, y):
return tnp.sum(x + y)
f(tnp.ones([1, 2]), tf.ones([2, 1]))
Python control flow based on ndarray
values will be translated by
autograph
into tf.cond
and tf.while_loop
constructs. The code can be XLA compiled
for further optimizations.
However, note that graph mode execution can change behavior of certain operations since symbolic execution may not have information that is computed during runtime. Some differences are:
- Shapes can be incomplete or unknown in graph mode. This means that
ndarray.shape
,ndarray.size
andndarray.ndim
can returnndarray
objects instead of returning integer (or tuple of integer) values. __len__
,__iter__
and__index__
properties ofndarray
may similarly not be supported in graph mode. Code using these may need to change to explicit shape operations or control flow constructs.- Also note the autograph limitations.
Mutation and Variables
ndarrays
currently wrap immutable tf.Tensor
. Hence mutation
operations like slice assigns are not supported. This may change in the future.
Note however that one can directly construct a tf.Variable
and use that with
the TF-NumPy APIs.
tf_var = tf.Variable(2.0)
tf_var.assign_add(tnp.square(tf_var))
Differences with NumPy
Here is a non-exhaustive list of differences:
- Not all dtypes are currently supported. e.g.
np.float96
,np.float128
.np.object
,np.str
,np.recarray
types are not supported. ndarray
storage is in C order only. Fortran order, views,stride_tricks
are not supported.- Only a subset of functions and modules are supported. This set will be
expanded over time. For supported functions, some arguments or argument
values may not be supported. These differences are generally provided in the
function comments. Full
ufunc
support is also not provided. - Buffer mutation is currently not supported.
ndarrays
wrap immutable tensors. This means that output buffer arguments (e.g.out
in ufuncs) are not supported. - NumPy C API is not supported. NumPy's Cython and Swig integration are not supported.
Modules
random
module: Public API for tf.experimental.numpy.random namespace.
Classes
class bool_
: Boolean type (True or False), stored as a byte.
class complex128
: Complex number type composed of two double-precision floating-point
class complex64
: Complex number type composed of two single-precision floating-point
class complex_
: Complex number type composed of two double-precision floating-point
class float16
: Half-precision floating-point number type.
class float32
: Single-precision floating-point number type, compatible with C float
.
class float64
: Double-precision floating-point number type, compatible with Python float
class float_
: Double-precision floating-point number type, compatible with Python float
class iinfo
: iinfo(type)
class inexact
: Abstract base class of all numeric scalar types with a (potentially)
class int16
: Signed integer type, compatible with C short
.
class int32
: Signed integer type, compatible with C int
.
class int64
: Signed integer type, compatible with Python int
anc C long
.
class int8
: Signed integer type, compatible with C char
.
class int_
: Signed integer type, compatible with Python int
anc C long
.
class ndarray
: A tensor is a multidimensional array of elements represented by a
class object_
: Any Python object.
class string_
: bytes(iterable_of_ints) -> bytes
class uint16
: Unsigned integer type, compatible with C unsigned short
.
class uint32
: Unsigned integer type, compatible with C unsigned int
.
class uint64
: Unsigned integer type, compatible with C unsigned long
.
class uint8
: Unsigned integer type, compatible with C unsigned char
.
class unicode_
: str(object='') -> str
Functions
abs(...)
: TensorFlow variant of NumPy's abs
.
absolute(...)
: TensorFlow variant of NumPy's absolute
.
add(...)
: TensorFlow variant of NumPy's add
.
all(...)
: TensorFlow variant of NumPy's all
.
allclose(...)
: TensorFlow variant of NumPy's allclose
.
amax(...)
: TensorFlow variant of NumPy's amax
.
amin(...)
: TensorFlow variant of NumPy's amin
.
angle(...)
: TensorFlow variant of NumPy's angle
.
any(...)
: TensorFlow variant of NumPy's any
.
append(...)
: TensorFlow variant of NumPy's append
.
arange(...)
: TensorFlow variant of NumPy's arange
.
arccos(...)
: TensorFlow variant of NumPy's arccos
.
arccosh(...)
: TensorFlow variant of NumPy's arccosh
.
arcsin(...)
: TensorFlow variant of NumPy's arcsin
.
arcsinh(...)
: TensorFlow variant of NumPy's arcsinh
.
arctan(...)
: TensorFlow variant of NumPy's arctan
.
arctan2(...)
: TensorFlow variant of NumPy's arctan2
.
arctanh(...)
: TensorFlow variant of NumPy's arctanh
.
argmax(...)
: TensorFlow variant of NumPy's argmax
.
argmin(...)
: TensorFlow variant of NumPy's argmin
.
argsort(...)
: TensorFlow variant of NumPy's argsort
.
around(...)
: TensorFlow variant of NumPy's around
.
array(...)
: TensorFlow variant of NumPy's array
.
array_equal(...)
: TensorFlow variant of NumPy's array_equal
.
asanyarray(...)
: TensorFlow variant of NumPy's asanyarray
.
asarray(...)
: TensorFlow variant of NumPy's asarray
.
ascontiguousarray(...)
: TensorFlow variant of NumPy's ascontiguousarray
.
atleast_1d(...)
: TensorFlow variant of NumPy's atleast_1d
.
atleast_2d(...)
: TensorFlow variant of NumPy's atleast_2d
.
atleast_3d(...)
: TensorFlow variant of NumPy's atleast_3d
.
average(...)
: TensorFlow variant of NumPy's average
.
bitwise_and(...)
: TensorFlow variant of NumPy's bitwise_and
.
bitwise_not(...)
: TensorFlow variant of NumPy's bitwise_not
.
bitwise_or(...)
: TensorFlow variant of NumPy's bitwise_or
.
bitwise_xor(...)
: TensorFlow variant of NumPy's bitwise_xor
.
broadcast_arrays(...)
: TensorFlow variant of NumPy's broadcast_arrays
.
broadcast_to(...)
: TensorFlow variant of NumPy's broadcast_to
.
cbrt(...)
: TensorFlow variant of NumPy's cbrt
.
ceil(...)
: TensorFlow variant of NumPy's ceil
.
clip(...)
: TensorFlow variant of NumPy's clip
.
compress(...)
: TensorFlow variant of NumPy's compress
.
concatenate(...)
: TensorFlow variant of NumPy's concatenate
.
conj(...)
: TensorFlow variant of NumPy's conj
.
conjugate(...)
: TensorFlow variant of NumPy's conjugate
.
copy(...)
: TensorFlow variant of NumPy's copy
.
cos(...)
: TensorFlow variant of NumPy's cos
.
cosh(...)
: TensorFlow variant of NumPy's cosh
.
count_nonzero(...)
: TensorFlow variant of NumPy's count_nonzero
.
cross(...)
: TensorFlow variant of NumPy's cross
.
cumprod(...)
: TensorFlow variant of NumPy's cumprod
.
cumsum(...)
: TensorFlow variant of NumPy's cumsum
.
deg2rad(...)
: TensorFlow variant of NumPy's deg2rad
.
diag(...)
: TensorFlow variant of NumPy's diag
.
diag_indices(...)
: TensorFlow variant of NumPy's diag_indices
.
diagflat(...)
: TensorFlow variant of NumPy's diagflat
.
diagonal(...)
: TensorFlow variant of NumPy's diagonal
.
diff(...)
: TensorFlow variant of NumPy's diff
.
divide(...)
: TensorFlow variant of NumPy's divide
.
divmod(...)
: TensorFlow variant of NumPy's divmod
.
dot(...)
: TensorFlow variant of NumPy's dot
.
dsplit(...)
: TensorFlow variant of NumPy's dsplit
.
dstack(...)
: TensorFlow variant of NumPy's dstack
.
einsum(...)
: TensorFlow variant of NumPy's einsum
.
empty(...)
: TensorFlow variant of NumPy's empty
.
empty_like(...)
: TensorFlow variant of NumPy's empty_like
.
equal(...)
: TensorFlow variant of NumPy's equal
.
exp(...)
: TensorFlow variant of NumPy's exp
.
exp2(...)
: TensorFlow variant of NumPy's exp2
.
expand_dims(...)
: TensorFlow variant of NumPy's expand_dims
.
experimental_enable_numpy_behavior(...)
: Enable NumPy behavior on Tensors.
expm1(...)
: TensorFlow variant of NumPy's expm1
.
eye(...)
: TensorFlow variant of NumPy's eye
.
fabs(...)
: TensorFlow variant of NumPy's fabs
.
finfo(...)
: TensorFlow variant of NumPy's finfo
.
fix(...)
: TensorFlow variant of NumPy's fix
.
flip(...)
: TensorFlow variant of NumPy's flip
.
fliplr(...)
: TensorFlow variant of NumPy's fliplr
.
flipud(...)
: TensorFlow variant of NumPy's flipud
.
float_power(...)
: TensorFlow variant of NumPy's float_power
.
floor(...)
: TensorFlow variant of NumPy's floor
.
floor_divide(...)
: TensorFlow variant of NumPy's floor_divide
.
full(...)
: TensorFlow variant of NumPy's full
.
full_like(...)
: TensorFlow variant of NumPy's full_like
.
gcd(...)
: TensorFlow variant of NumPy's gcd
.
geomspace(...)
: TensorFlow variant of NumPy's geomspace
.
greater(...)
: TensorFlow variant of NumPy's greater
.
greater_equal(...)
: TensorFlow variant of NumPy's greater_equal
.
heaviside(...)
: TensorFlow variant of NumPy's heaviside
.
hsplit(...)
: TensorFlow variant of NumPy's hsplit
.
hstack(...)
: TensorFlow variant of NumPy's hstack
.
hypot(...)
: TensorFlow variant of NumPy's hypot
.
identity(...)
: TensorFlow variant of NumPy's identity
.
imag(...)
: TensorFlow variant of NumPy's imag
.
inner(...)
: TensorFlow variant of NumPy's inner
.
isclose(...)
: TensorFlow variant of NumPy's isclose
.
iscomplex(...)
: TensorFlow variant of NumPy's iscomplex
.
iscomplexobj(...)
: TensorFlow variant of NumPy's iscomplexobj
.
isfinite(...)
: TensorFlow variant of NumPy's isfinite
.
isinf(...)
: TensorFlow variant of NumPy's isinf
.
isnan(...)
: TensorFlow variant of NumPy's isnan
.
isneginf(...)
: TensorFlow variant of NumPy's isneginf
.
isposinf(...)
: TensorFlow variant of NumPy's isposinf
.
isreal(...)
: TensorFlow variant of NumPy's isreal
.
isrealobj(...)
: TensorFlow variant of NumPy's isrealobj
.
isscalar(...)
: TensorFlow variant of NumPy's isscalar
.
issubdtype(...)
: Returns True if first argument is a typecode lower/equal in type hierarchy.
ix_(...)
: TensorFlow variant of NumPy's ix_
.
kron(...)
: TensorFlow variant of NumPy's kron
.
lcm(...)
: TensorFlow variant of NumPy's lcm
.
less(...)
: TensorFlow variant of NumPy's less
.
less_equal(...)
: TensorFlow variant of NumPy's less_equal
.
linspace(...)
: TensorFlow variant of NumPy's linspace
.
log(...)
: TensorFlow variant of NumPy's log
.
log10(...)
: TensorFlow variant of NumPy's log10
.
log1p(...)
: TensorFlow variant of NumPy's log1p
.
log2(...)
: TensorFlow variant of NumPy's log2
.
logaddexp(...)
: TensorFlow variant of NumPy's logaddexp
.
logaddexp2(...)
: TensorFlow variant of NumPy's logaddexp2
.
logical_and(...)
: TensorFlow variant of NumPy's logical_and
.
logical_not(...)
: TensorFlow variant of NumPy's logical_not
.
logical_or(...)
: TensorFlow variant of NumPy's logical_or
.
logical_xor(...)
: TensorFlow variant of NumPy's logical_xor
.
logspace(...)
: TensorFlow variant of NumPy's logspace
.
matmul(...)
: TensorFlow variant of NumPy's matmul
.
max(...)
: TensorFlow variant of NumPy's max
.
maximum(...)
: TensorFlow variant of NumPy's maximum
.
mean(...)
: TensorFlow variant of NumPy's mean
.
meshgrid(...)
: TensorFlow variant of NumPy's meshgrid
.
min(...)
: TensorFlow variant of NumPy's min
.
minimum(...)
: TensorFlow variant of NumPy's minimum
.
mod(...)
: TensorFlow variant of NumPy's mod
.
moveaxis(...)
: TensorFlow variant of NumPy's moveaxis
.
multiply(...)
: TensorFlow variant of NumPy's multiply
.
nanmean(...)
: TensorFlow variant of NumPy's nanmean
.
nanprod(...)
: TensorFlow variant of NumPy's nanprod
.
nansum(...)
: TensorFlow variant of NumPy's nansum
.
ndim(...)
: TensorFlow variant of NumPy's ndim
.
negative(...)
: TensorFlow variant of NumPy's negative
.
nextafter(...)
: TensorFlow variant of NumPy's nextafter
.
nonzero(...)
: TensorFlow variant of NumPy's nonzero
.
not_equal(...)
: TensorFlow variant of NumPy's not_equal
.
ones(...)
: TensorFlow variant of NumPy's ones
.
ones_like(...)
: TensorFlow variant of NumPy's ones_like
.
outer(...)
: TensorFlow variant of NumPy's outer
.
pad(...)
: TensorFlow variant of NumPy's pad
.
polyval(...)
: TensorFlow variant of NumPy's polyval
.
positive(...)
: TensorFlow variant of NumPy's positive
.
power(...)
: TensorFlow variant of NumPy's power
.
prod(...)
: TensorFlow variant of NumPy's prod
.
promote_types(...)
: TensorFlow variant of NumPy's promote_types
.
ptp(...)
: TensorFlow variant of NumPy's ptp
.
rad2deg(...)
: TensorFlow variant of NumPy's rad2deg
.
ravel(...)
: TensorFlow variant of NumPy's ravel
.
real(...)
: TensorFlow variant of NumPy's real
.
reciprocal(...)
: TensorFlow variant of NumPy's reciprocal
.
remainder(...)
: TensorFlow variant of NumPy's remainder
.
repeat(...)
: TensorFlow variant of NumPy's repeat
.
reshape(...)
: TensorFlow variant of NumPy's reshape
.
result_type(...)
: TensorFlow variant of NumPy's result_type
.
roll(...)
: TensorFlow variant of NumPy's roll
.
rot90(...)
: TensorFlow variant of NumPy's rot90
.
round(...)
: TensorFlow variant of NumPy's round
.
select(...)
: TensorFlow variant of NumPy's select
.
shape(...)
: TensorFlow variant of NumPy's shape
.
sign(...)
: TensorFlow variant of NumPy's sign
.
signbit(...)
: TensorFlow variant of NumPy's signbit
.
sin(...)
: TensorFlow variant of NumPy's sin
.
sinc(...)
: TensorFlow variant of NumPy's sinc
.
sinh(...)
: TensorFlow variant of NumPy's sinh
.
size(...)
: TensorFlow variant of NumPy's size
.
sort(...)
: TensorFlow variant of NumPy's sort
.
split(...)
: TensorFlow variant of NumPy's split
.
sqrt(...)
: TensorFlow variant of NumPy's sqrt
.
square(...)
: TensorFlow variant of NumPy's square
.
squeeze(...)
: TensorFlow variant of NumPy's squeeze
.
stack(...)
: TensorFlow variant of NumPy's stack
.
std(...)
: TensorFlow variant of NumPy's std
.
subtract(...)
: TensorFlow variant of NumPy's subtract
.
sum(...)
: TensorFlow variant of NumPy's sum
.
swapaxes(...)
: TensorFlow variant of NumPy's swapaxes
.
take(...)
: TensorFlow variant of NumPy's take
.
take_along_axis(...)
: TensorFlow variant of NumPy's take_along_axis
.
tan(...)
: TensorFlow variant of NumPy's tan
.
tanh(...)
: TensorFlow variant of NumPy's tanh
.
tensordot(...)
: TensorFlow variant of NumPy's tensordot
.
tile(...)
: TensorFlow variant of NumPy's tile
.
trace(...)
: TensorFlow variant of NumPy's trace
.
transpose(...)
: TensorFlow variant of NumPy's transpose
.
tri(...)
: TensorFlow variant of NumPy's tri
.
tril(...)
: TensorFlow variant of NumPy's tril
.
triu(...)
: TensorFlow variant of NumPy's triu
.
true_divide(...)
: TensorFlow variant of NumPy's true_divide
.
vander(...)
: TensorFlow variant of NumPy's vander
.
var(...)
: TensorFlow variant of NumPy's var
.
vdot(...)
: TensorFlow variant of NumPy's vdot
.
vsplit(...)
: TensorFlow variant of NumPy's vsplit
.
vstack(...)
: TensorFlow variant of NumPy's vstack
.
where(...)
: TensorFlow variant of NumPy's where
.
zeros(...)
: TensorFlow variant of NumPy's zeros
.
zeros_like(...)
: TensorFlow variant of NumPy's zeros_like
.
Other Members | |
---|---|
e |
2.718281828459045
|
inf |
inf
|
newaxis |
None
|
pi |
3.141592653589793
|