numpy.lib.emath

module documentation

Wrapper functions to more user-friendly calling of certain math functions whose output data-type is different than the input data-type in certain domains of the input.

For example, for functions like log with branch cuts, the versions in this module provide the mathematically valid answers in the complex plane:

>>> import math
>>> np.emath.log(-math.exp(1)) == (1+1j*math.pi)
True

Similarly, sqrt, other base logarithms, power and trig functions are correctly handled. See their respective docstrings for specific examples.

Functions

Function	`_fix_int_lt_zero`	Convert `x` to double if it has real, negative components.
Function	`_fix_real_abs_gt_1`	Convert `x` to complex if it has real components x_i with abs(x_i)>1.
Function	`_fix_real_lt_zero`	Convert `x` to complex if it has real, negative components.
Function	`_logn_dispatcher`	Undocumented
Function	`_power_dispatcher`	Undocumented
Function	`_tocomplex`	Convert its input `arr` to a complex array.
Function	`_unary_dispatcher`	Undocumented
Function	`arccos`	Compute the inverse cosine of x.
Function	`arcsin`	Compute the inverse sine of x.
Function	`arctanh`	Compute the inverse hyperbolic tangent of `x`.
Function	`log`	Compute the natural logarithm of `x`.
Function	`log10`	Compute the logarithm base 10 of `x`.
Function	`log2`	Compute the logarithm base 2 of `x`.
Function	`logn`	Take log base n of x.
Function	`power`	Return x to the power p, (x**p).
Function	`sqrt`	Compute the square root of x.
Variable	`_ln2`	Undocumented

def _fix_int_lt_zero(x):

Convert x to double if it has real, negative components.

Otherwise, output is just the array version of the input (via asarray).

Parameters

x : array_like

Returns

array

Examples

>>> np.lib.scimath._fix_int_lt_zero([1,2])
array([1, 2])

>>> np.lib.scimath._fix_int_lt_zero([-1,2])
array([-1.,  2.])

def _fix_real_abs_gt_1(x):

Convert x to complex if it has real components x_i with abs(x_i)>1.

Otherwise, output is just the array version of the input (via asarray).

Parameters

x : array_like

Returns

array

Examples

>>> np.lib.scimath._fix_real_abs_gt_1([0,1])
array([0, 1])

>>> np.lib.scimath._fix_real_abs_gt_1([0,2])
array([0.+0.j, 2.+0.j])

def _fix_real_lt_zero(x):

Convert x to complex if it has real, negative components.

Otherwise, output is just the array version of the input (via asarray).

Parameters

x : array_like

Returns

array

Examples

>>> np.lib.scimath._fix_real_lt_zero([1,2])
array([1, 2])

>>> np.lib.scimath._fix_real_lt_zero([-1,2])
array([-1.+0.j,  2.+0.j])

def _logn_dispatcher(n, x):

Undocumented

def _power_dispatcher(x, p):

Undocumented

def _tocomplex(arr):

Convert its input arr to a complex array.

The input is returned as a complex array of the smallest type that will fit the original data: types like single, byte, short, etc. become csingle, while others become cdouble.

A copy of the input is always made.

Parameters

arr : array

Returns

array: An array with the same input data as the input but in complex form.

Examples

First, consider an input of type short:

>>> a = np.array([1,2,3],np.short)

>>> ac = np.lib.scimath._tocomplex(a); ac
array([1.+0.j, 2.+0.j, 3.+0.j], dtype=complex64)

>>> ac.dtype
dtype('complex64')

If the input is of type double, the output is correspondingly of the complex double type as well:

>>> b = np.array([1,2,3],np.double)

>>> bc = np.lib.scimath._tocomplex(b); bc
array([1.+0.j, 2.+0.j, 3.+0.j])

>>> bc.dtype
dtype('complex128')

Note that even if the input was complex to begin with, a copy is still made, since the astype() method always copies:

>>> c = np.array([1,2,3],np.csingle)

>>> cc = np.lib.scimath._tocomplex(c); cc
array([1.+0.j,  2.+0.j,  3.+0.j], dtype=complex64)

>>> c *= 2; c
array([2.+0.j,  4.+0.j,  6.+0.j], dtype=complex64)

>>> cc
array([1.+0.j,  2.+0.j,  3.+0.j], dtype=complex64)

def _unary_dispatcher(x):

Undocumented

@array_function_dispatch(_unary_dispatcher)
def arccos(x):

Compute the inverse cosine of x.

Return the "principal value" (for a description of this, see numpy.arccos) of the inverse cosine of x. For real x such that abs(x) <= 1, this is a real number in the closed interval [0, π]. Otherwise, the complex principle value is returned.

Parameters

x : array_like or scalar: The value(s) whose arccos is (are) required.

Returns

out : ndarray or scalar: The inverse cosine(s) of the x value(s). If x was a scalar, so is out, otherwise an array object is returned.

Notes

For an arccos() that returns NAN when real x is not in the interval [-1,1], use numpy.arccos.

Examples

>>> np.set_printoptions(precision=4)

>>> np.emath.arccos(1) # a scalar is returned
0.0

>>> np.emath.arccos([1,2])
array([0.-0.j   , 0.-1.317j])

@array_function_dispatch(_unary_dispatcher)
def arcsin(x):

Compute the inverse sine of x.

Return the "principal value" (for a description of this, see numpy.arcsin) of the inverse sine of x. For real x such that abs(x) <= 1, this is a real number in the closed interval [ − π ⁄ 2, π ⁄ 2]. Otherwise, the complex principle value is returned.

Parameters

x : array_like or scalar: The value(s) whose arcsin is (are) required.

Returns

out : ndarray or scalar: The inverse sine(s) of the x value(s). If x was a scalar, so is out, otherwise an array object is returned.

Notes

For an arcsin() that returns NAN when real x is not in the interval [-1,1], use numpy.arcsin.

Examples

>>> np.set_printoptions(precision=4)

>>> np.emath.arcsin(0)
0.0

>>> np.emath.arcsin([0,1])
array([0.    , 1.5708])

@array_function_dispatch(_unary_dispatcher)
def arctanh(x):

Compute the inverse hyperbolic tangent of x.

Return the "principal value" (for a description of this, see numpy.arctanh) of arctanh(x). For real x such that abs(x) < 1, this is a real number. If abs(x) > 1, or if x is complex, the result is complex. Finally, x = 1 returns``inf`` and x=-1 returns -inf.

Parameters

x : array_like: The value(s) whose arctanh is (are) required.

Returns

out : ndarray or scalar: The inverse hyperbolic tangent(s) of the x value(s). If x was a scalar so is out, otherwise an array is returned.

Notes

For an arctanh() that returns NAN when real x is not in the interval (-1,1), use numpy.arctanh (this latter, however, does return +/-inf for x = +/-1).

Examples

>>> np.set_printoptions(precision=4)

>>> from numpy.testing import suppress_warnings
>>> with suppress_warnings() as sup:
...     sup.filter(RuntimeWarning)
...     np.emath.arctanh(np.eye(2))
array([[inf,  0.],
       [ 0., inf]])
>>> np.emath.arctanh([1j])
array([0.+0.7854j])

@array_function_dispatch(_unary_dispatcher)
def log(x):

Compute the natural logarithm of x.

Return the "principal value" (for a description of this, see numpy.log) of log_e(x). For real x > 0, this is a real number (log(0) returns -inf and log(np.inf) returns inf). Otherwise, the complex principle value is returned.

Parameters

x : array_like: The value(s) whose log is (are) required.

Returns

out : ndarray or scalar: The log of the x value(s). If x was a scalar, so is out, otherwise an array is returned.

Notes

For a log() that returns NAN when real x < 0, use numpy.log (note, however, that otherwise numpy.log and this log are identical, i.e., both return -inf for x = 0, inf for x = inf, and, notably, the complex principle value if x.imag != 0).

Examples

>>> np.emath.log(np.exp(1))
1.0

Negative arguments are handled "correctly" (recall that exp(log(x)) == x does not hold for real x < 0):

>>> np.emath.log(-np.exp(1)) == (1 + np.pi * 1j)
True

@array_function_dispatch(_unary_dispatcher)
def log10(x):

Compute the logarithm base 10 of x.

Return the "principal value" (for a description of this, see numpy.log10) of log₁₀(x). For real x > 0, this is a real number (log10(0) returns -inf and log10(np.inf) returns inf). Otherwise, the complex principle value is returned.

Parameters

x : array_like or scalar: The value(s) whose log base 10 is (are) required.

Returns

out : ndarray or scalar: The log base 10 of the x value(s). If x was a scalar, so is out, otherwise an array object is returned.

Notes

For a log10() that returns NAN when real x < 0, use numpy.log10 (note, however, that otherwise numpy.log10 and this log10 are identical, i.e., both return -inf for x = 0, inf for x = inf, and, notably, the complex principle value if x.imag != 0).

Examples

(We set the printing precision so the example can be auto-tested)

>>> np.set_printoptions(precision=4)

>>> np.emath.log10(10**1)
1.0

>>> np.emath.log10([-10**1, -10**2, 10**2])
array([1.+1.3644j, 2.+1.3644j, 2.+0.j    ])

@array_function_dispatch(_unary_dispatcher)
def log2(x):

Compute the logarithm base 2 of x.

Return the "principal value" (for a description of this, see numpy.log2) of log₂(x). For real x > 0, this is a real number (log2(0) returns -inf and log2(np.inf) returns inf). Otherwise, the complex principle value is returned.

Parameters

x : array_like: The value(s) whose log base 2 is (are) required.

Returns

out : ndarray or scalar: The log base 2 of the x value(s). If x was a scalar, so is out, otherwise an array is returned.

Notes

For a log2() that returns NAN when real x < 0, use numpy.log2 (note, however, that otherwise numpy.log2 and this log2 are identical, i.e., both return -inf for x = 0, inf for x = inf, and, notably, the complex principle value if x.imag != 0).

Examples

We set the printing precision so the example can be auto-tested:

>>> np.set_printoptions(precision=4)

>>> np.emath.log2(8)
3.0
>>> np.emath.log2([-4, -8, 8])
array([2.+4.5324j, 3.+4.5324j, 3.+0.j    ])

@array_function_dispatch(_logn_dispatcher)
def logn(n, x):

Take log base n of x.

If x contains negative inputs, the answer is computed and returned in the complex domain.

Parameters

n : array_like: The integer base(s) in which the log is taken.
x : array_like: The value(s) whose log base n is (are) required.

Returns

out : ndarray or scalar: The log base n of the x value(s). If x was a scalar, so is out, otherwise an array is returned.

Examples

>>> np.set_printoptions(precision=4)

>>> np.emath.logn(2, [4, 8])
array([2., 3.])
>>> np.emath.logn(2, [-4, -8, 8])
array([2.+4.5324j, 3.+4.5324j, 3.+0.j    ])

@array_function_dispatch(_power_dispatcher)
def power(x, p):

Return x to the power p, (x**p).

If x contains negative values, the output is converted to the complex domain.

Parameters

x : array_like: The input value(s).
p : array_like of ints: The power(s) to which x is raised. If x contains multiple values, p has to either be a scalar, or contain the same number of values as x. In the latter case, the result is x[0]**p[0], x[1]**p[1], ....

Returns

out : ndarray or scalar: The result of x**p. If x and p are scalars, so is out, otherwise an array is returned.

Examples

>>> np.set_printoptions(precision=4)

>>> np.emath.power([2, 4], 2)
array([ 4, 16])
>>> np.emath.power([2, 4], -2)
array([0.25  ,  0.0625])
>>> np.emath.power([-2, 4], 2)
array([ 4.-0.j, 16.+0.j])

@array_function_dispatch(_unary_dispatcher)
def sqrt(x):

Compute the square root of x.

For negative input elements, a complex value is returned (unlike numpy.sqrt which returns NaN).

Parameters

x : array_like: The input value(s).

Returns

out : ndarray or scalar: The square root of x. If x was a scalar, so is out, otherwise an array is returned.

Examples

For real, non-negative inputs this works just like numpy.sqrt:

>>> np.emath.sqrt(1)
1.0
>>> np.emath.sqrt([1, 4])
array([1.,  2.])

But it automatically handles negative inputs:

>>> np.emath.sqrt(-1)
1j
>>> np.emath.sqrt([-1,4])
array([0.+1.j, 2.+0.j])

_ln2 =

Undocumented

numpy.lib.emath

Functions

Parameters

Returns

Examples

Parameters

Returns

Examples

Parameters

Returns

Examples

Parameters

Returns

Examples

Parameters

Returns

See Also

Notes

Examples

Parameters

Returns

See Also

Notes

Examples

Parameters

Returns

See Also

Notes

Examples

Parameters

Returns

See Also

Notes

Examples

Parameters

Returns

See Also

Notes

Examples

Parameters

Returns

See Also

Notes

Examples

Parameters

Returns

Examples

Parameters

Returns

See Also

Examples

Parameters

Returns

See Also

Examples

`numpy.lib.emath`