1"""Automatically adapted for numpy Sep 19, 2005 by convertcode.py

2

3"""

4 import functools

5 import warnings

6

7__all__ = ['iscomplexobj', 'isrealobj', 'imag', 'iscomplex',

8 'isreal', 'nan_to_num', 'real', 'real_if_close',

9 'typename', 'asfarray', 'mintypecode',

10 'common_type']

11

12 import numpy.core.numeric as _nx

13 from numpy.core.numeric import asarray, asanyarray, isnan, zeros

14 from numpy.core.overrides import set_module

15 from numpy.core import overrides

16 from .ufunclike import isneginf, isposinf

17

18

19 array_function_dispatch = functools.partial(

20 overrides.array_function_dispatch, module='numpy')

21

22

23_typecodes_by_elsize = 'GDFgdfQqLlIiHhBb?'

24

25

26@set_module('numpy')

27 def mintypecode(typechars, typeset='GDFgdf', default='d'):

28 """

29 Return the character for the minimum-size type to which given types can

30 be safely cast.

31

32 The returned type character must represent the smallest size dtype such

33 that an array of the returned type can handle the data from an array of

34 all types in `typechars` (or if `typechars` is an array, then its

35 dtype.char).

36

37 Parameters

38 ----------

39 typechars : list of str or array_like

40 If a list of strings, each string should represent a dtype.

41 If array_like, the character representation of the array dtype is used.

42 typeset : str or list of str, optional

43 The set of characters that the returned character is chosen from.

44 The default set is 'GDFgdf'.

45 default : str, optional

46 The default character, this is returned if none of the characters in

47 `typechars` matches a character in `typeset`.

48

49 Returns

50 -------

51 typechar : str

52 The character representing the minimum-size type that was found.

53

54 See Also

55 --------

56 dtype, sctype2char, maximum_sctype

57

58 Examples

59 --------

60 >>> np.mintypecode(['d', 'f', 'S'])

61 'd'

62 >>> x = np.array([1.1, 2-3.j])

63 >>> np.mintypecode(x)

64 'D'

65

66 >>> np.mintypecode('abceh', default='G')

67 'G'

68

69 """

70 typecodes = ((isinstance(t, str) and t) or asarray(t).dtype.char

71 for t in typechars)

72 intersection = set(t for t in typecodes if t in typeset)

73 if not intersection:

74 return default

75 if 'F' in intersection and 'd' in intersection:

76 return 'D'

77 return min(intersection, key=_typecodes_by_elsize.index)

78

79

80 def _asfarray_dispatcher(a, dtype=None):

81 return (a,)

82

83

84@array_function_dispatch(_asfarray_dispatcher)

85 def asfarray(a, dtype=_nx.float_):

86 """

87 Return an array converted to a float type.

88

89 Parameters

90 ----------

91 a : array_like

92 The input array.

93 dtype : str or dtype object, optional

94 Float type code to coerce input array `a`. If `dtype` is one of the

95 'int' dtypes, it is replaced with float64.

96

97 Returns

98 -------

99 out : ndarray

100 The input `a` as a float ndarray.

101

102 Examples

103 --------

104 >>> np.asfarray([2, 3])

105 array([2., 3.])

106 >>> np.asfarray([2, 3], dtype='float')

107 array([2., 3.])

108 >>> np.asfarray([2, 3], dtype='int8')

109 array([2., 3.])

110

111 """

112 if not _nx.issubdtype(dtype, _nx.inexact):

113 dtype = _nx.float_

114 return asarray(a, dtype=dtype)

115

116

117 def _real_dispatcher(val):

118 return (val,)

119

120

121@array_function_dispatch(_real_dispatcher)

122 def real(val):

123 """

124 Return the real part of the complex argument.

125

126 Parameters

127 ----------

128 val : array_like

129 Input array.

130

131 Returns

132 -------

133 out : ndarray or scalar

134 The real component of the complex argument. If `val` is real, the type

135 of `val` is used for the output. If `val` has complex elements, the

136 returned type is float.

137

138 See Also

139 --------

140 real_if_close, imag, angle

141

142 Examples

143 --------

144 >>> a = np.array([1+2j, 3+4j, 5+6j])

145 >>> a.real

146 array([1., 3., 5.])

147 >>> a.real = 9

148 >>> a

149 array([9.+2.j, 9.+4.j, 9.+6.j])

150 >>> a.real = np.array([9, 8, 7])

151 >>> a

152 array([9.+2.j, 8.+4.j, 7.+6.j])

153 >>> np.real(1 + 1j)

154 1.0

155

156 """

157 try:

158 return val.real

159 except AttributeError:

160 return asanyarray(val).real

161

162

163 def _imag_dispatcher(val):

164 return (val,)

165

166

167@array_function_dispatch(_imag_dispatcher)

168 def imag(val):

169 """

170 Return the imaginary part of the complex argument.

171

172 Parameters

173 ----------

174 val : array_like

175 Input array.

176

177 Returns

178 -------

179 out : ndarray or scalar

180 The imaginary component of the complex argument. If `val` is real,

181 the type of `val` is used for the output. If `val` has complex

182 elements, the returned type is float.

183

184 See Also

185 --------

186 real, angle, real_if_close

187

188 Examples

189 --------

190 >>> a = np.array([1+2j, 3+4j, 5+6j])

191 >>> a.imag

192 array([2., 4., 6.])

193 >>> a.imag = np.array([8, 10, 12])

194 >>> a

195 array([1. +8.j, 3.+10.j, 5.+12.j])

196 >>> np.imag(1 + 1j)

197 1.0

198

199 """

200 try:

201 return val.imag

202 except AttributeError:

203 return asanyarray(val).imag

204

205

206 def _is_type_dispatcher(x):

207 return (x,)

208

209

210@array_function_dispatch(_is_type_dispatcher)

211 def iscomplex(x):

212 """

213 Returns a bool array, where True if input element is complex.

214

215 What is tested is whether the input has a non-zero imaginary part, not if

216 the input type is complex.

217

218 Parameters

219 ----------

220 x : array_like

221 Input array.

222

223 Returns

224 -------

225 out : ndarray of bools

226 Output array.

227

228 See Also

229 --------

230 isreal

231 iscomplexobj : Return True if x is a complex type or an array of complex

232 numbers.

233

234 Examples

235 --------

236 >>> np.iscomplex([1+1j, 1+0j, 4.5, 3, 2, 2j])

237 array([ True, False, False, False, False, True])

238

239 """

240 ax = asanyarray(x)

241 if issubclass(ax.dtype.type, _nx.complexfloating):

242 return ax.imag != 0

243 res = zeros(ax.shape, bool)

244 return res[()] # convert to scalar if needed

245

246

247@array_function_dispatch(_is_type_dispatcher)

248 def isreal(x):

249 """

250 Returns a bool array, where True if input element is real.

251

252 If element has complex type with zero complex part, the return value

253 for that element is True.

254

255 Parameters

256 ----------

257 x : array_like

258 Input array.

259

260 Returns

261 -------

262 out : ndarray, bool

263 Boolean array of same shape as `x`.

264

265 Notes

266 -----

267 `isreal` may behave unexpectedly for string or object arrays (see examples)

268

269 See Also

270 --------

271 iscomplex

272 isrealobj : Return True if x is not a complex type.

273

274 Examples

275 --------

276 >>> a = np.array([1+1j, 1+0j, 4.5, 3, 2, 2j], dtype=complex)

277 >>> np.isreal(a)

278 array([False, True, True, True, True, False])

279

280 The function does not work on string arrays.

281

282 >>> a = np.array([2j, "a"], dtype="U")

283 >>> np.isreal(a) # Warns about non-elementwise comparison

284 False

285

286 Returns True for all elements in input array of ``dtype=object`` even if

287 any of the elements is complex.

288

289 >>> a = np.array([1, "2", 3+4j], dtype=object)

290 >>> np.isreal(a)

291 array([ True, True, True])

292

293 isreal should not be used with object arrays

294

295 >>> a = np.array([1+2j, 2+1j], dtype=object)

296 >>> np.isreal(a)

297 array([ True, True])

298

299 """

300 return imag(x) == 0

301

302

303@array_function_dispatch(_is_type_dispatcher)

304 def iscomplexobj(x):

305 """

306 Check for a complex type or an array of complex numbers.

307

308 The type of the input is checked, not the value. Even if the input

309 has an imaginary part equal to zero, `iscomplexobj` evaluates to True.

310

311 Parameters

312 ----------

313 x : any

314 The input can be of any type and shape.

315

316 Returns

317 -------

318 iscomplexobj : bool

319 The return value, True if `x` is of a complex type or has at least

320 one complex element.

321

322 See Also

323 --------

324 isrealobj, iscomplex

325

326 Examples

327 --------

328 >>> np.iscomplexobj(1)

329 False

330 >>> np.iscomplexobj(1+0j)

331 True

332 >>> np.iscomplexobj([3, 1+0j, True])

333 True

334

335 """

336 try:

337 dtype = x.dtype

338 type_ = dtype.type

339 except AttributeError:

340 type_ = asarray(x).dtype.type

341 return issubclass(type_, _nx.complexfloating)

342

343

344@array_function_dispatch(_is_type_dispatcher)

345 def isrealobj(x):

346 """

347 Return True if x is a not complex type or an array of complex numbers.

348

349 The type of the input is checked, not the value. So even if the input

350 has an imaginary part equal to zero, `isrealobj` evaluates to False

351 if the data type is complex.

352

353 Parameters

354 ----------

355 x : any

356 The input can be of any type and shape.

357

358 Returns

359 -------

360 y : bool

361 The return value, False if `x` is of a complex type.

362

363 See Also

364 --------

365 iscomplexobj, isreal

366

367 Notes

368 -----

369 The function is only meant for arrays with numerical values but it

370 accepts all other objects. Since it assumes array input, the return

371 value of other objects may be True.

372

373 >>> np.isrealobj('A string')

374 True

375 >>> np.isrealobj(False)

376 True

377 >>> np.isrealobj(None)

378 True

379

380 Examples

381 --------

382 >>> np.isrealobj(1)

383 True

384 >>> np.isrealobj(1+0j)

385 False

386 >>> np.isrealobj([3, 1+0j, True])

387 False

388

389 """

390 return not iscomplexobj(x)

391

392#-----------------------------------------------------------------------------

393

394 def _getmaxmin(t):

395 from numpy.core import getlimits

396 f = getlimits.finfo(t)

397 return f.max, f.min

398

399

400 def _nan_to_num_dispatcher(x, copy=None, nan=None, posinf=None, neginf=None):

401 return (x,)

402

403

404@array_function_dispatch(_nan_to_num_dispatcher)

405 def nan_to_num(x, copy=True, nan=0.0, posinf=None, neginf=None):

406 """

407 Replace NaN with zero and infinity with large finite numbers (default

408 behaviour) or with the numbers defined by the user using the `nan`,

409 `posinf` and/or `neginf` keywords.

410

411 If `x` is inexact, NaN is replaced by zero or by the user defined value in

412 `nan` keyword, infinity is replaced by the largest finite floating point

413 values representable by ``x.dtype`` or by the user defined value in

414 `posinf` keyword and -infinity is replaced by the most negative finite

415 floating point values representable by ``x.dtype`` or by the user defined

416 value in `neginf` keyword.

417

418 For complex dtypes, the above is applied to each of the real and

419 imaginary components of `x` separately.

420

421 If `x` is not inexact, then no replacements are made.

422

423 Parameters

424 ----------

425 x : scalar or array_like

426 Input data.

427 copy : bool, optional

428 Whether to create a copy of `x` (True) or to replace values

429 in-place (False). The in-place operation only occurs if

430 casting to an array does not require a copy.

431 Default is True.

432

433 .. versionadded:: 1.13

434 nan : int, float, optional

435 Value to be used to fill NaN values. If no value is passed

436 then NaN values will be replaced with 0.0.

437

438 .. versionadded:: 1.17

439 posinf : int, float, optional

440 Value to be used to fill positive infinity values. If no value is

441 passed then positive infinity values will be replaced with a very

442 large number.

443

444 .. versionadded:: 1.17

445 neginf : int, float, optional

446 Value to be used to fill negative infinity values. If no value is

447 passed then negative infinity values will be replaced with a very

448 small (or negative) number.

449

450 .. versionadded:: 1.17

451

452

453

454 Returns

455 -------

456 out : ndarray

457 `x`, with the non-finite values replaced. If `copy` is False, this may

458 be `x` itself.

459

460 See Also

461 --------

462 isinf : Shows which elements are positive or negative infinity.

463 isneginf : Shows which elements are negative infinity.

464 isposinf : Shows which elements are positive infinity.

465 isnan : Shows which elements are Not a Number (NaN).

466 isfinite : Shows which elements are finite (not NaN, not infinity)

467

468 Notes

469 -----

470 NumPy uses the IEEE Standard for Binary Floating-Point for Arithmetic

471 (IEEE 754). This means that Not a Number is not equivalent to infinity.

472

473 Examples

474 --------

475 >>> np.nan_to_num(np.inf)

476 1.7976931348623157e+308

477 >>> np.nan_to_num(-np.inf)

478 -1.7976931348623157e+308

479 >>> np.nan_to_num(np.nan)

480 0.0

481 >>> x = np.array([np.inf, -np.inf, np.nan, -128, 128])

482 >>> np.nan_to_num(x)

483 array([ 1.79769313e+308, -1.79769313e+308, 0.00000000e+000, # may vary

484 -1.28000000e+002, 1.28000000e+002])

485 >>> np.nan_to_num(x, nan=-9999, posinf=33333333, neginf=33333333)

486 array([ 3.3333333e+07, 3.3333333e+07, -9.9990000e+03,

487 -1.2800000e+02, 1.2800000e+02])

488 >>> y = np.array([complex(np.inf, np.nan), np.nan, complex(np.nan, np.inf)])

489 array([ 1.79769313e+308, -1.79769313e+308, 0.00000000e+000, # may vary

490 -1.28000000e+002, 1.28000000e+002])

491 >>> np.nan_to_num(y)

492 array([ 1.79769313e+308 +0.00000000e+000j, # may vary

493 0.00000000e+000 +0.00000000e+000j,

494 0.00000000e+000 +1.79769313e+308j])

495 >>> np.nan_to_num(y, nan=111111, posinf=222222)

496 array([222222.+111111.j, 111111. +0.j, 111111.+222222.j])

497 """

498 x = _nx.array(x, subok=True, copy=copy)

499 xtype = x.dtype.type

500

501 isscalar = (x.ndim == 0)

502

503 if not issubclass(xtype, _nx.inexact):

504 return x[()] if isscalar else x

505

506 iscomplex = issubclass(xtype, _nx.complexfloating)

507

508 dest = (x.real, x.imag) if iscomplex else (x,)

509 maxf, minf = _getmaxmin(x.real.dtype)

510 if posinf is not None:

511 maxf = posinf

512 if neginf is not None:

513 minf = neginf

514 for d in dest:

515 idx_nan = isnan(d)

516 idx_posinf = isposinf(d)

517 idx_neginf = isneginf(d)

518 _nx.copyto(d, nan, where=idx_nan)

519 _nx.copyto(d, maxf, where=idx_posinf)

520 _nx.copyto(d, minf, where=idx_neginf)

521 return x[()] if isscalar else x

522

523#-----------------------------------------------------------------------------

524

525 def _real_if_close_dispatcher(a, tol=None):

526 return (a,)

527

528

529@array_function_dispatch(_real_if_close_dispatcher)

530 def real_if_close(a, tol=100):

531 """

532 If input is complex with all imaginary parts close to zero, return

533 real parts.

534

535 "Close to zero" is defined as `tol` * (machine epsilon of the type for

536 `a`).

537

538 Parameters

539 ----------

540 a : array_like

541 Input array.

542 tol : float

543 Tolerance in machine epsilons for the complex part of the elements

544 in the array.

545

546 Returns

547 -------

548 out : ndarray

549 If `a` is real, the type of `a` is used for the output. If `a`

550 has complex elements, the returned type is float.

551

552 See Also

553 --------

554 real, imag, angle

555

556 Notes

557 -----

558 Machine epsilon varies from machine to machine and between data types

559 but Python floats on most platforms have a machine epsilon equal to

560 2.2204460492503131e-16. You can use 'np.finfo(float).eps' to print

561 out the machine epsilon for floats.

562

563 Examples

564 --------

565 >>> np.finfo(float).eps

566 2.2204460492503131e-16 # may vary

567

568 >>> np.real_if_close([2.1 + 4e-14j, 5.2 + 3e-15j], tol=1000)

569 array([2.1, 5.2])

570 >>> np.real_if_close([2.1 + 4e-13j, 5.2 + 3e-15j], tol=1000)

571 array([2.1+4.e-13j, 5.2 + 3e-15j])

572

573 """

574 a = asanyarray(a)

575 if not issubclass(a.dtype.type, _nx.complexfloating):

576 return a

577 if tol > 1:

578 from numpy.core import getlimits

579 f = getlimits.finfo(a.dtype.type)

580 tol = f.eps * tol

581 if _nx.all(_nx.absolute(a.imag) < tol):

582 a = a.real

583 return a

584

585

586#-----------------------------------------------------------------------------

587

588_namefromtype = {'S1': 'character',

589 '?': 'bool',

590 'b': 'signed char',

591 'B': 'unsigned char',

592 'h': 'short',

593 'H': 'unsigned short',

594 'i': 'integer',

595 'I': 'unsigned integer',

596 'l': 'long integer',

597 'L': 'unsigned long integer',

598 'q': 'long long integer',

599 'Q': 'unsigned long long integer',

600 'f': 'single precision',

601 'd': 'double precision',

602 'g': 'long precision',

603 'F': 'complex single precision',

604 'D': 'complex double precision',

605 'G': 'complex long double precision',

606 'S': 'string',

607 'U': 'unicode',

608 'V': 'void',

609 'O': 'object'

610 }

611

612@set_module('numpy')

613 def typename(char):

614 """

615 Return a description for the given data type code.

616

617 Parameters

618 ----------

619 char : str

620 Data type code.

621

622 Returns

623 -------

624 out : str

625 Description of the input data type code.

626

627 See Also

628 --------

629 dtype, typecodes

630

631 Examples

632 --------

633 >>> typechars = ['S1', '?', 'B', 'D', 'G', 'F', 'I', 'H', 'L', 'O', 'Q',

634 ... 'S', 'U', 'V', 'b', 'd', 'g', 'f', 'i', 'h', 'l', 'q']

635 >>> for typechar in typechars:

636 ... print(typechar, ' : ', np.typename(typechar))

637 ...

638 S1 : character

639 ? : bool

640 B : unsigned char

641 D : complex double precision

642 G : complex long double precision

643 F : complex single precision

644 I : unsigned integer

645 H : unsigned short

646 L : unsigned long integer

647 O : object

648 Q : unsigned long long integer

649 S : string

650 U : unicode

651 V : void

652 b : signed char

653 d : double precision

654 g : long precision

655 f : single precision

656 i : integer

657 h : short

658 l : long integer

659 q : long long integer

660

661 """

662 return _namefromtype[char]

663

664#-----------------------------------------------------------------------------

665

666#determine the "minimum common type" for a group of arrays.

667 array_type = [[_nx.half, _nx.single, _nx.double, _nx.longdouble],

668 [None, _nx.csingle, _nx.cdouble, _nx.clongdouble]]

669 array_precision = {_nx.half: 0,

670 _nx.single: 1,

671 _nx.double: 2,

672 _nx.longdouble: 3,

673 _nx.csingle: 1,

674 _nx.cdouble: 2,

675 _nx.clongdouble: 3}

676

677

678 def _common_type_dispatcher(*arrays):

679 return arrays

680

681

682@array_function_dispatch(_common_type_dispatcher)

683 def common_type(*arrays):

684 """

685 Return a scalar type which is common to the input arrays.

686

687 The return type will always be an inexact (i.e. floating point) scalar

688 type, even if all the arrays are integer arrays. If one of the inputs is

689 an integer array, the minimum precision type that is returned is a

690 64-bit floating point dtype.

691

692 All input arrays except int64 and uint64 can be safely cast to the

693 returned dtype without loss of information.

694

695 Parameters

696 ----------

697 array1, array2, ... : ndarrays

698 Input arrays.

699

700 Returns

701 -------

702 out : data type code

703 Data type code.

704

705 See Also

706 --------

707 dtype, mintypecode

708

709 Examples

710 --------

711 >>> np.common_type(np.arange(2, dtype=np.float32))

712 <class 'numpy.float32'>

713 >>> np.common_type(np.arange(2, dtype=np.float32), np.arange(2))

714 <class 'numpy.float64'>

715 >>> np.common_type(np.arange(4), np.array([45, 6.j]), np.array([45.0]))

716 <class 'numpy.complex128'>

717

718 """

719 is_complex = False

720 precision = 0

721 for a in arrays:

722 t = a.dtype.type

723 if iscomplexobj(a):

724 is_complex = True

725 if issubclass(t, _nx.integer):

726 p = 2 # array_precision[_nx.double]

727 else:

728 p = array_precision.get(t, None)

729 if p is None:

730 raise TypeError("can't get common type for non-numeric array")

731 precision = max(precision, p)

732 if is_complex:

733 return array_type[1][precision]

734 else:

735 return array_type[0][precision]