Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/tensorflow/_api/v2/experimental/numpy/__init__.py: 31%

1# This file is MACHINE GENERATED! Do not edit. 

2# Generated by: tensorflow/python/tools/api/generator/create_python_api.py script. 

3"""# tf.experimental.numpy: NumPy API on TensorFlow. 

4 

5This module provides a subset of NumPy API, built on top of TensorFlow 

6operations. APIs are based on and have been tested with NumPy 1.16 version. 

7 

8The set of supported APIs may be expanded over time. Also future releases may 

9change the baseline version of NumPy API being supported. A list of some 

10systematic differences with NumPy is listed later in the "Differences with 

11NumPy" section. 

12 

13## Getting Started 

14 

15Please also see [TensorFlow NumPy Guide]( 

16https://www.tensorflow.org/guide/tf_numpy). 

17 

18In the code snippets below, we will assume that `tf.experimental.numpy` is 

19imported as `tnp` and NumPy is imported as `np` 

20 

21```python 

22print(tnp.ones([2,1]) + np.ones([1, 2])) 

23``` 

24 

25## Types 

26 

27The module provides an `ndarray` class which wraps an immutable `tf.Tensor`. 

28Additional functions are provided which accept array-like objects. Here 

29array-like objects include `ndarrays` as defined by this module, as well as 

30`tf.Tensor`, in addition to types accepted by NumPy. 

31 

32A subset of NumPy dtypes are supported. Type promotion follows NumPy 

33semantics. 

34 

35```python 

36print(tnp.ones([1, 2], dtype=tnp.int16) + tnp.ones([2, 1], dtype=tnp.uint8)) 

37``` 

38 

39## Array Interface 

40 

41The `ndarray` class implements the `__array__` interface. This should allow 

42these objects to be passed into contexts that expect a NumPy or array-like 

43object (e.g. matplotlib). 

44 

45```python 

46np.sum(tnp.ones([1, 2]) + np.ones([2, 1])) 

47``` 

48 

49 

50## TF Interoperability 

51 

52The TF-NumPy API calls can be interleaved with TensorFlow calls 

53without incurring Tensor data copies. This is true even if the `ndarray` or 

54`tf.Tensor` is placed on a non-CPU device. 

55 

56In general, the expected behavior should be on par with that of code involving 

57`tf.Tensor` and running stateless TensorFlow functions on them. 

58 

59```python 

60tnp.sum(tnp.ones([1, 2]) + tf.ones([2, 1])) 

61``` 

62 

63Note that the `__array_priority__` is currently chosen to be lower than 

64`tf.Tensor`. Hence the `+` operator above returns a `tf.Tensor`. 

65 

66Additional examples of interoperability include: 

67 

68* using `with tf.GradientTape()` scope to compute gradients through the 

69 TF-NumPy API calls. 

70* using `tf.distribution.Strategy` scope for distributed execution 

71* using `tf.vectorized_map()` for speeding up code using auto-vectorization 

72 

73 

74 

75## Device Support 

76 

77Given that `ndarray` and functions wrap TensorFlow constructs, the code will 

78have GPU and TPU support on par with TensorFlow. Device placement can be 

79controlled by using `with tf.device` scopes. Note that these devices could 

80be local or remote. 

81 

82```python 

83with tf.device("GPU:0"): 

84 x = tnp.ones([1, 2]) 

85print(tf.convert_to_tensor(x).device) 

86``` 

87 

88## Graph and Eager Modes 

89 

90Eager mode execution should typically match NumPy semantics of executing 

91op-by-op. However the same code can be executed in graph mode, by putting it 

92inside a `tf.function`. The function body can contain NumPy code, and the inputs 

93can be `ndarray` as well. 

94 

95```python 

96@tf.function 

97def f(x, y): 

98 return tnp.sum(x + y) 

99 

100f(tnp.ones([1, 2]), tf.ones([2, 1])) 

101``` 

102Python control flow based on `ndarray` values will be translated by 

103[autograph](https://www.tensorflow.org/code/tensorflow/python/autograph/g3doc/reference/index.md) 

104into `tf.cond` and `tf.while_loop` constructs. The code can be XLA compiled 

105for further optimizations. 

106 

107However, note that graph mode execution can change behavior of certain 

108operations since symbolic execution may not have information that is computed 

109during runtime. Some differences are: 

110 

111* Shapes can be incomplete or unknown in graph mode. This means that 

112 `ndarray.shape`, `ndarray.size` and `ndarray.ndim` can return `ndarray` 

113 objects instead of returning integer (or tuple of integer) values. 

114* `__len__`, `__iter__` and `__index__` properties of `ndarray` 

115 may similarly not be supported in graph mode. Code using these 

116 may need to change to explicit shape operations or control flow 

117 constructs. 

118* Also note the [autograph limitations]( 

119https://github.com/tensorflow/tensorflow/blob/master/tensorflow/python/autograph/g3doc/reference/limitations.md). 

120 

121 

122## Mutation and Variables 

123 

124`ndarrays` currently wrap immutable `tf.Tensor`. Hence mutation 

125operations like slice assigns are not supported. This may change in the future. 

126Note however that one can directly construct a `tf.Variable` and use that with 

127the TF-NumPy APIs. 

128 

129```python 

130tf_var = tf.Variable(2.0) 

131tf_var.assign_add(tnp.square(tf_var)) 

132``` 

133 

134## Differences with NumPy 

135 

136Here is a non-exhaustive list of differences: 

137 

138* Not all dtypes are currently supported. e.g. `np.float96`, `np.float128`. 

139 `np.object_`, `np.str_`, `np.recarray` types are not supported. 

140* `ndarray` storage is in C order only. Fortran order, views, `stride_tricks` 

141 are not supported. 

142* Only a subset of functions and modules are supported. This set will be 

143 expanded over time. For supported functions, some arguments or argument 

144 values may not be supported. These differences are generally provided in the 

145 function comments. Full `ufunc` support is also not provided. 

146* Buffer mutation is currently not supported. `ndarrays` wrap immutable 

147 tensors. This means that output buffer arguments (e.g. `out` in ufuncs) are 

148 not supported. 

149* NumPy C API is not supported. NumPy's Cython and Swig integration are not 

150 supported. 

151 

152""" 

153 

154import sys as _sys 

155 

156from . import random 

157from tensorflow.python.framework.tensor import Tensor as ndarray 

158from tensorflow.python.ops.numpy_ops.np_array_ops import all 

159from tensorflow.python.ops.numpy_ops.np_array_ops import amax 

160from tensorflow.python.ops.numpy_ops.np_array_ops import amin 

161from tensorflow.python.ops.numpy_ops.np_array_ops import any 

162from tensorflow.python.ops.numpy_ops.np_array_ops import arange 

163from tensorflow.python.ops.numpy_ops.np_array_ops import around 

164from tensorflow.python.ops.numpy_ops.np_array_ops import array 

165from tensorflow.python.ops.numpy_ops.np_array_ops import asanyarray 

166from tensorflow.python.ops.numpy_ops.np_array_ops import asarray 

167from tensorflow.python.ops.numpy_ops.np_array_ops import ascontiguousarray 

168from tensorflow.python.ops.numpy_ops.np_array_ops import atleast_1d 

169from tensorflow.python.ops.numpy_ops.np_array_ops import atleast_2d 

170from tensorflow.python.ops.numpy_ops.np_array_ops import atleast_3d 

171from tensorflow.python.ops.numpy_ops.np_array_ops import broadcast_arrays 

172from tensorflow.python.ops.numpy_ops.np_array_ops import broadcast_to 

173from tensorflow.python.ops.numpy_ops.np_array_ops import compress 

174from tensorflow.python.ops.numpy_ops.np_array_ops import copy 

175from tensorflow.python.ops.numpy_ops.np_array_ops import cumprod 

176from tensorflow.python.ops.numpy_ops.np_array_ops import cumsum 

177from tensorflow.python.ops.numpy_ops.np_array_ops import diag 

178from tensorflow.python.ops.numpy_ops.np_array_ops import diag_indices 

179from tensorflow.python.ops.numpy_ops.np_array_ops import diagflat 

180from tensorflow.python.ops.numpy_ops.np_array_ops import diagonal 

181from tensorflow.python.ops.numpy_ops.np_array_ops import dsplit 

182from tensorflow.python.ops.numpy_ops.np_array_ops import dstack 

183from tensorflow.python.ops.numpy_ops.np_array_ops import empty 

184from tensorflow.python.ops.numpy_ops.np_array_ops import empty_like 

185from tensorflow.python.ops.numpy_ops.np_array_ops import expand_dims 

186from tensorflow.python.ops.numpy_ops.np_array_ops import eye 

187from tensorflow.python.ops.numpy_ops.np_array_ops import flatten 

188from tensorflow.python.ops.numpy_ops.np_array_ops import flip 

189from tensorflow.python.ops.numpy_ops.np_array_ops import fliplr 

190from tensorflow.python.ops.numpy_ops.np_array_ops import flipud 

191from tensorflow.python.ops.numpy_ops.np_array_ops import full 

192from tensorflow.python.ops.numpy_ops.np_array_ops import full_like 

193from tensorflow.python.ops.numpy_ops.np_array_ops import hsplit 

194from tensorflow.python.ops.numpy_ops.np_array_ops import hstack 

195from tensorflow.python.ops.numpy_ops.np_array_ops import identity 

196from tensorflow.python.ops.numpy_ops.np_array_ops import imag 

197from tensorflow.python.ops.numpy_ops.np_array_ops import isscalar 

198from tensorflow.python.ops.numpy_ops.np_array_ops import ix_ 

199from tensorflow.python.ops.numpy_ops.np_array_ops import max 

200from tensorflow.python.ops.numpy_ops.np_array_ops import mean 

201from tensorflow.python.ops.numpy_ops.np_array_ops import min 

202from tensorflow.python.ops.numpy_ops.np_array_ops import moveaxis 

203from tensorflow.python.ops.numpy_ops.np_array_ops import ndim 

204from tensorflow.python.ops.numpy_ops.np_array_ops import newaxis 

205from tensorflow.python.ops.numpy_ops.np_array_ops import nonzero 

206from tensorflow.python.ops.numpy_ops.np_array_ops import ones 

207from tensorflow.python.ops.numpy_ops.np_array_ops import ones_like 

208from tensorflow.python.ops.numpy_ops.np_array_ops import pad 

209from tensorflow.python.ops.numpy_ops.np_array_ops import prod 

210from tensorflow.python.ops.numpy_ops.np_array_ops import ravel 

211from tensorflow.python.ops.numpy_ops.np_array_ops import real 

212from tensorflow.python.ops.numpy_ops.np_array_ops import repeat 

213from tensorflow.python.ops.numpy_ops.np_array_ops import reshape 

214from tensorflow.python.ops.numpy_ops.np_array_ops import roll 

215from tensorflow.python.ops.numpy_ops.np_array_ops import rot90 

216from tensorflow.python.ops.numpy_ops.np_array_ops import round 

217from tensorflow.python.ops.numpy_ops.np_array_ops import select 

218from tensorflow.python.ops.numpy_ops.np_array_ops import shape 

219from tensorflow.python.ops.numpy_ops.np_array_ops import sign 

220from tensorflow.python.ops.numpy_ops.np_array_ops import size 

221from tensorflow.python.ops.numpy_ops.np_array_ops import split 

222from tensorflow.python.ops.numpy_ops.np_array_ops import squeeze 

223from tensorflow.python.ops.numpy_ops.np_array_ops import stack 

224from tensorflow.python.ops.numpy_ops.np_array_ops import std 

225from tensorflow.python.ops.numpy_ops.np_array_ops import sum 

226from tensorflow.python.ops.numpy_ops.np_array_ops import swapaxes 

227from tensorflow.python.ops.numpy_ops.np_array_ops import take 

228from tensorflow.python.ops.numpy_ops.np_array_ops import take_along_axis 

229from tensorflow.python.ops.numpy_ops.np_array_ops import transpose 

230from tensorflow.python.ops.numpy_ops.np_array_ops import tri 

231from tensorflow.python.ops.numpy_ops.np_array_ops import tril 

232from tensorflow.python.ops.numpy_ops.np_array_ops import triu 

233from tensorflow.python.ops.numpy_ops.np_array_ops import vander 

234from tensorflow.python.ops.numpy_ops.np_array_ops import var 

235from tensorflow.python.ops.numpy_ops.np_array_ops import vsplit 

236from tensorflow.python.ops.numpy_ops.np_array_ops import vstack 

237from tensorflow.python.ops.numpy_ops.np_array_ops import where 

238from tensorflow.python.ops.numpy_ops.np_array_ops import zeros 

239from tensorflow.python.ops.numpy_ops.np_array_ops import zeros_like 

240from tensorflow.python.ops.numpy_ops.np_config import enable_numpy_behavior as experimental_enable_numpy_behavior 

241from tensorflow.python.ops.numpy_ops.np_dtypes import bool_ 

242from tensorflow.python.ops.numpy_ops.np_dtypes import complex128 

243from tensorflow.python.ops.numpy_ops.np_dtypes import complex64 

244from tensorflow.python.ops.numpy_ops.np_dtypes import complex_ 

245from tensorflow.python.ops.numpy_ops.np_dtypes import float16 

246from tensorflow.python.ops.numpy_ops.np_dtypes import float32 

247from tensorflow.python.ops.numpy_ops.np_dtypes import float64 

248from tensorflow.python.ops.numpy_ops.np_dtypes import float_ 

249from tensorflow.python.ops.numpy_ops.np_dtypes import iinfo 

250from tensorflow.python.ops.numpy_ops.np_dtypes import inexact 

251from tensorflow.python.ops.numpy_ops.np_dtypes import int16 

252from tensorflow.python.ops.numpy_ops.np_dtypes import int32 

253from tensorflow.python.ops.numpy_ops.np_dtypes import int64 

254from tensorflow.python.ops.numpy_ops.np_dtypes import int8 

255from tensorflow.python.ops.numpy_ops.np_dtypes import int_ 

256from tensorflow.python.ops.numpy_ops.np_dtypes import issubdtype 

257from tensorflow.python.ops.numpy_ops.np_dtypes import object_ 

258from tensorflow.python.ops.numpy_ops.np_dtypes import string_ 

259from tensorflow.python.ops.numpy_ops.np_dtypes import uint16 

260from tensorflow.python.ops.numpy_ops.np_dtypes import uint32 

261from tensorflow.python.ops.numpy_ops.np_dtypes import uint64 

262from tensorflow.python.ops.numpy_ops.np_dtypes import uint8 

263from tensorflow.python.ops.numpy_ops.np_dtypes import unicode_ 

264from tensorflow.python.ops.numpy_ops.np_math_ops import abs 

265from tensorflow.python.ops.numpy_ops.np_math_ops import absolute 

266from tensorflow.python.ops.numpy_ops.np_math_ops import add 

267from tensorflow.python.ops.numpy_ops.np_math_ops import allclose 

268from tensorflow.python.ops.numpy_ops.np_math_ops import angle 

269from tensorflow.python.ops.numpy_ops.np_math_ops import append 

270from tensorflow.python.ops.numpy_ops.np_math_ops import arccos 

271from tensorflow.python.ops.numpy_ops.np_math_ops import arccosh 

272from tensorflow.python.ops.numpy_ops.np_math_ops import arcsin 

273from tensorflow.python.ops.numpy_ops.np_math_ops import arcsinh 

274from tensorflow.python.ops.numpy_ops.np_math_ops import arctan 

275from tensorflow.python.ops.numpy_ops.np_math_ops import arctan2 

276from tensorflow.python.ops.numpy_ops.np_math_ops import arctanh 

277from tensorflow.python.ops.numpy_ops.np_math_ops import argmax 

278from tensorflow.python.ops.numpy_ops.np_math_ops import argmin 

279from tensorflow.python.ops.numpy_ops.np_math_ops import argsort 

280from tensorflow.python.ops.numpy_ops.np_math_ops import array_equal 

281from tensorflow.python.ops.numpy_ops.np_math_ops import average 

282from tensorflow.python.ops.numpy_ops.np_math_ops import bitwise_and 

283from tensorflow.python.ops.numpy_ops.np_math_ops import bitwise_not 

284from tensorflow.python.ops.numpy_ops.np_math_ops import bitwise_or 

285from tensorflow.python.ops.numpy_ops.np_math_ops import bitwise_xor 

286from tensorflow.python.ops.numpy_ops.np_math_ops import cbrt 

287from tensorflow.python.ops.numpy_ops.np_math_ops import ceil 

288from tensorflow.python.ops.numpy_ops.np_math_ops import clip 

289from tensorflow.python.ops.numpy_ops.np_math_ops import concatenate 

290from tensorflow.python.ops.numpy_ops.np_math_ops import conj 

291from tensorflow.python.ops.numpy_ops.np_math_ops import conjugate 

292from tensorflow.python.ops.numpy_ops.np_math_ops import cos 

293from tensorflow.python.ops.numpy_ops.np_math_ops import cosh 

294from tensorflow.python.ops.numpy_ops.np_math_ops import count_nonzero 

295from tensorflow.python.ops.numpy_ops.np_math_ops import cross 

296from tensorflow.python.ops.numpy_ops.np_math_ops import deg2rad 

297from tensorflow.python.ops.numpy_ops.np_math_ops import diff 

298from tensorflow.python.ops.numpy_ops.np_math_ops import divide 

299from tensorflow.python.ops.numpy_ops.np_math_ops import divmod 

300from tensorflow.python.ops.numpy_ops.np_math_ops import dot 

301from tensorflow.python.ops.numpy_ops.np_math_ops import e 

302from tensorflow.python.ops.numpy_ops.np_math_ops import einsum 

303from tensorflow.python.ops.numpy_ops.np_math_ops import equal 

304from tensorflow.python.ops.numpy_ops.np_math_ops import exp 

305from tensorflow.python.ops.numpy_ops.np_math_ops import exp2 

306from tensorflow.python.ops.numpy_ops.np_math_ops import expm1 

307from tensorflow.python.ops.numpy_ops.np_math_ops import fabs 

308from tensorflow.python.ops.numpy_ops.np_math_ops import fix 

309from tensorflow.python.ops.numpy_ops.np_math_ops import float_power 

310from tensorflow.python.ops.numpy_ops.np_math_ops import floor 

311from tensorflow.python.ops.numpy_ops.np_math_ops import floor_divide 

312from tensorflow.python.ops.numpy_ops.np_math_ops import gcd 

313from tensorflow.python.ops.numpy_ops.np_math_ops import geomspace 

314from tensorflow.python.ops.numpy_ops.np_math_ops import greater 

315from tensorflow.python.ops.numpy_ops.np_math_ops import greater_equal 

316from tensorflow.python.ops.numpy_ops.np_math_ops import heaviside 

317from tensorflow.python.ops.numpy_ops.np_math_ops import hypot 

318from tensorflow.python.ops.numpy_ops.np_math_ops import inf 

319from tensorflow.python.ops.numpy_ops.np_math_ops import inner 

320from tensorflow.python.ops.numpy_ops.np_math_ops import isclose 

321from tensorflow.python.ops.numpy_ops.np_math_ops import iscomplex 

322from tensorflow.python.ops.numpy_ops.np_math_ops import iscomplexobj 

323from tensorflow.python.ops.numpy_ops.np_math_ops import isfinite 

324from tensorflow.python.ops.numpy_ops.np_math_ops import isinf 

325from tensorflow.python.ops.numpy_ops.np_math_ops import isnan 

326from tensorflow.python.ops.numpy_ops.np_math_ops import isneginf 

327from tensorflow.python.ops.numpy_ops.np_math_ops import isposinf 

328from tensorflow.python.ops.numpy_ops.np_math_ops import isreal 

329from tensorflow.python.ops.numpy_ops.np_math_ops import isrealobj 

330from tensorflow.python.ops.numpy_ops.np_math_ops import kron 

331from tensorflow.python.ops.numpy_ops.np_math_ops import lcm 

332from tensorflow.python.ops.numpy_ops.np_math_ops import less 

333from tensorflow.python.ops.numpy_ops.np_math_ops import less_equal 

334from tensorflow.python.ops.numpy_ops.np_math_ops import linspace 

335from tensorflow.python.ops.numpy_ops.np_math_ops import log 

336from tensorflow.python.ops.numpy_ops.np_math_ops import log10 

337from tensorflow.python.ops.numpy_ops.np_math_ops import log1p 

338from tensorflow.python.ops.numpy_ops.np_math_ops import log2 

339from tensorflow.python.ops.numpy_ops.np_math_ops import logaddexp 

340from tensorflow.python.ops.numpy_ops.np_math_ops import logaddexp2 

341from tensorflow.python.ops.numpy_ops.np_math_ops import logical_and 

342from tensorflow.python.ops.numpy_ops.np_math_ops import logical_not 

343from tensorflow.python.ops.numpy_ops.np_math_ops import logical_or 

344from tensorflow.python.ops.numpy_ops.np_math_ops import logical_xor 

345from tensorflow.python.ops.numpy_ops.np_math_ops import logspace 

346from tensorflow.python.ops.numpy_ops.np_math_ops import matmul 

347from tensorflow.python.ops.numpy_ops.np_math_ops import maximum 

348from tensorflow.python.ops.numpy_ops.np_math_ops import meshgrid 

349from tensorflow.python.ops.numpy_ops.np_math_ops import minimum 

350from tensorflow.python.ops.numpy_ops.np_math_ops import mod 

351from tensorflow.python.ops.numpy_ops.np_math_ops import multiply 

352from tensorflow.python.ops.numpy_ops.np_math_ops import nanmean 

353from tensorflow.python.ops.numpy_ops.np_math_ops import nanprod 

354from tensorflow.python.ops.numpy_ops.np_math_ops import nansum 

355from tensorflow.python.ops.numpy_ops.np_math_ops import negative 

356from tensorflow.python.ops.numpy_ops.np_math_ops import nextafter 

357from tensorflow.python.ops.numpy_ops.np_math_ops import not_equal 

358from tensorflow.python.ops.numpy_ops.np_math_ops import outer 

359from tensorflow.python.ops.numpy_ops.np_math_ops import pi 

360from tensorflow.python.ops.numpy_ops.np_math_ops import polyval 

361from tensorflow.python.ops.numpy_ops.np_math_ops import positive 

362from tensorflow.python.ops.numpy_ops.np_math_ops import power 

363from tensorflow.python.ops.numpy_ops.np_math_ops import ptp 

364from tensorflow.python.ops.numpy_ops.np_math_ops import rad2deg 

365from tensorflow.python.ops.numpy_ops.np_math_ops import reciprocal 

366from tensorflow.python.ops.numpy_ops.np_math_ops import remainder 

367from tensorflow.python.ops.numpy_ops.np_math_ops import signbit 

368from tensorflow.python.ops.numpy_ops.np_math_ops import sin 

369from tensorflow.python.ops.numpy_ops.np_math_ops import sinc 

370from tensorflow.python.ops.numpy_ops.np_math_ops import sinh 

371from tensorflow.python.ops.numpy_ops.np_math_ops import sort 

372from tensorflow.python.ops.numpy_ops.np_math_ops import sqrt 

373from tensorflow.python.ops.numpy_ops.np_math_ops import square 

374from tensorflow.python.ops.numpy_ops.np_math_ops import subtract 

375from tensorflow.python.ops.numpy_ops.np_math_ops import tan 

376from tensorflow.python.ops.numpy_ops.np_math_ops import tanh 

377from tensorflow.python.ops.numpy_ops.np_math_ops import tensordot 

378from tensorflow.python.ops.numpy_ops.np_math_ops import tile 

379from tensorflow.python.ops.numpy_ops.np_math_ops import trace 

380from tensorflow.python.ops.numpy_ops.np_math_ops import true_divide 

381from tensorflow.python.ops.numpy_ops.np_math_ops import vdot 

382from tensorflow.python.ops.numpy_ops.np_utils import finfo 

383from tensorflow.python.ops.numpy_ops.np_utils import promote_types 

384from tensorflow.python.ops.numpy_ops.np_utils import result_type