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 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.
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
Variable _ln2 Undocumented

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.

See Also

numpy.arccos

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])
Parameters
x:array_like or scalarThe value(s) whose arccos is (are) required.
Returns
ndarray or scalarout - The inverse cosine(s) of the x value(s). If x was a scalar, so is out, otherwise an array object is returned.

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.

See Also

numpy.arcsin

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])
Parameters
x:array_like or scalarThe value(s) whose arcsin is (are) required.
Returns
ndarray or scalarout - The inverse sine(s) of the x value(s). If x was a scalar, so is out, otherwise an array object is returned.

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.

See Also

numpy.arctanh

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])
Parameters
x:array_likeThe value(s) whose arctanh is (are) required.
Returns
ndarray or scalarout - The inverse hyperbolic tangent(s) of the x value(s). If x was a scalar so is out, otherwise an array is returned.

Compute the natural logarithm of x.

Return the "principal value" (for a description of this, see numpy.log) of loge(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.

See Also

numpy.log

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
Parameters
x:array_likeThe value(s) whose log is (are) required.
Returns
ndarray or scalarout - The log of the x value(s). If x was a scalar, so is out, otherwise an array is returned.

Compute the logarithm base 10 of x.

Return the "principal value" (for a description of this, see numpy.log10) of log10(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.

See Also

numpy.log10

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    ])
Parameters
x:array_like or scalarThe value(s) whose log base 10 is (are) required.
Returns
ndarray or scalarout - The log base 10 of the x value(s). If x was a scalar, so is out, otherwise an array object is returned.

Compute the logarithm base 2 of x.

Return the "principal value" (for a description of this, see numpy.log2) of log2(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.

See Also

numpy.log2

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    ])
Parameters
x:array_likeThe value(s) whose log base 2 is (are) required.
Returns
ndarray or scalarout - The log base 2 of the x value(s). If x was a scalar, so is out, otherwise an array is returned.

Take log base n of x.

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

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    ])
Parameters
n:array_likeThe integer base(s) in which the log is taken.
x:array_likeThe value(s) whose log base n is (are) required.
Returns
ndarray or scalarout - The log base n of the x value(s). If x was a scalar, so is out, otherwise an array is returned.

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

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

See Also

numpy.power

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])
Parameters
x:array_likeThe input value(s).
p:array_like of intsThe 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
ndarray or scalarout - The result of x**p. If x and p are scalars, so is out, otherwise an array is returned.

Compute the square root of x.

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

See Also

numpy.sqrt

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])

Different results are expected because: floating point 0.0 and -0.0 are distinct.

For more control, explicitly use complex() as follows:

>>> np.emath.sqrt(complex(-4.0, 0.0))
2j
>>> np.emath.sqrt(complex(-4.0, -0.0))
-2j
Parameters
x:array_likeThe input value(s).
Returns
ndarray or scalarout - The square root of x. If x was a scalar, so is out, otherwise an array is returned.
def _fix_int_lt_zero(x): (source)

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

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

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.])
Parameters
x:array_like
Returns
arrayUndocumented
def _fix_real_abs_gt_1(x): (source)

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).

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])
Parameters
x:array_like
Returns
arrayUndocumented
def _fix_real_lt_zero(x): (source)

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

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

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])
Parameters
x:array_like
Returns
arrayUndocumented
def _logn_dispatcher(n, x): (source)

Undocumented

def _power_dispatcher(x, p): (source)

Undocumented

def _tocomplex(arr): (source)

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.

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)
Parameters
arr:array
Returns
arrayAn array with the same input data as the input but in complex form.
def _unary_dispatcher(x): (source)

Undocumented

Undocumented