diff options
| -rw-r--r-- | numpy/add_newdocs.py | 77 | ||||
| -rw-r--r-- | numpy/core/code_generators/ufunc_docstrings.py | 443 | ||||
| -rw-r--r-- | numpy/core/src/umath/umathmodule.c | 96 |
3 files changed, 364 insertions, 252 deletions
diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py index 6934cadcc..30d5a68ea 100644 --- a/numpy/add_newdocs.py +++ b/numpy/add_newdocs.py @@ -4693,45 +4693,6 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('view', # ############################################################################## -add_newdoc('numpy.core.umath', 'frexp', - """ - Return normalized fraction and exponent of 2 of input array, element-wise. - - Returns (`out1`, `out2`) from equation ``x` = out1 * 2**out2``. - - Parameters - ---------- - x : array_like - Input array. - - Returns - ------- - (out1, out2) : tuple of ndarrays, (float, int) - `out1` is a float array with values between -1 and 1. - `out2` is an int array which represent the exponent of 2. - - See Also - -------- - ldexp : Compute ``y = x1 * 2**x2``, the inverse of `frexp`. - - Notes - ----- - Complex dtypes are not supported, they will raise a TypeError. - - Examples - -------- - >>> x = np.arange(9) - >>> y1, y2 = np.frexp(x) - >>> y1 - array([ 0. , 0.5 , 0.5 , 0.75 , 0.5 , 0.625, 0.75 , 0.875, - 0.5 ]) - >>> y2 - array([0, 1, 2, 2, 3, 3, 3, 3, 4]) - >>> y1 * 2**y2 - array([ 0., 1., 2., 3., 4., 5., 6., 7., 8.]) - - """) - add_newdoc('numpy.core.umath', 'frompyfunc', """ frompyfunc(func, nin, nout) @@ -4772,44 +4733,6 @@ add_newdoc('numpy.core.umath', 'frompyfunc', """) -add_newdoc('numpy.core.umath', 'ldexp', - """ - Compute y = x1 * 2**x2. - - Parameters - ---------- - x1 : array_like - The array of multipliers. - x2 : array_like - The array of exponents. - - Returns - ------- - y : array_like - The output array, the result of ``x1 * 2**x2``. - - See Also - -------- - frexp : Return (y1, y2) from ``x = y1 * 2**y2``, the inverse of `ldexp`. - - Notes - ----- - Complex dtypes are not supported, they will raise a TypeError. - - `ldexp` is useful as the inverse of `frexp`, if used by itself it is - more clear to simply use the expression ``x1 * 2**x2``. - - Examples - -------- - >>> np.ldexp(5, np.arange(4)) - array([ 5., 10., 20., 40.], dtype=float32) - - >>> x = np.arange(6) - >>> np.ldexp(*np.frexp(x)) - array([ 0., 1., 2., 3., 4., 5.]) - - """) - add_newdoc('numpy.core.umath', 'geterrobj', """ geterrobj() diff --git a/numpy/core/code_generators/ufunc_docstrings.py b/numpy/core/code_generators/ufunc_docstrings.py index 59e877750..4d302969e 100644 --- a/numpy/core/code_generators/ufunc_docstrings.py +++ b/numpy/core/code_generators/ufunc_docstrings.py @@ -162,7 +162,7 @@ add_newdoc('numpy.core.umath', 'arccos', add_newdoc('numpy.core.umath', 'arccosh', """ - Inverse hyperbolic cosine, elementwise. + Inverse hyperbolic cosine, element-wise. Parameters ---------- @@ -272,7 +272,7 @@ add_newdoc('numpy.core.umath', 'arcsin', add_newdoc('numpy.core.umath', 'arcsinh', """ - Inverse hyperbolic sine elementwise. + Inverse hyperbolic sine element-wise. Parameters ---------- @@ -467,7 +467,7 @@ add_newdoc('numpy.core.umath', '_arg', add_newdoc('numpy.core.umath', 'arctanh', """ - Inverse hyperbolic tangent elementwise. + Inverse hyperbolic tangent element-wise. Parameters ---------- @@ -486,15 +486,15 @@ add_newdoc('numpy.core.umath', 'arctanh', Notes ----- `arctanh` is a multivalued function: for each `x` there are infinitely - many numbers `z` such that `tanh(z) = x`. The convention is to return the - `z` whose imaginary part lies in `[-pi/2, pi/2]`. + many numbers `z` such that `tanh(z) = x`. The convention is to return + the `z` whose imaginary part lies in `[-pi/2, pi/2]`. For real-valued input data types, `arctanh` always returns real output. - For each value that cannot be expressed as a real number or infinity, it - yields ``nan`` and sets the `invalid` floating point error flag. + For each value that cannot be expressed as a real number or infinity, + it yields ``nan`` and sets the `invalid` floating point error flag. - For complex-valued input, `arctanh` is a complex analytical function that - has branch cuts `[-1, -inf]` and `[1, inf]` and is continuous from + For complex-valued input, `arctanh` is a complex analytical function + that has branch cuts `[-1, -inf]` and `[1, inf]` and is continuous from above on the former and from below on the latter. The inverse hyperbolic tangent is also known as `atanh` or ``tanh^-1``. @@ -524,7 +524,7 @@ add_newdoc('numpy.core.umath', 'bitwise_and', Parameters ---------- x1, x2 : array_like - Only integer types are handled (including booleans). + Only integer and boolean types are handled. Returns ------- @@ -575,7 +575,7 @@ add_newdoc('numpy.core.umath', 'bitwise_or', Parameters ---------- x1, x2 : array_like - Only integer types are handled (including booleans). + Only integer and boolean types are handled. out : ndarray, optional Array into which the output is placed. Its type is preserved and it must be of the right shape to hold the output. See doc.ufuncs. @@ -634,7 +634,7 @@ add_newdoc('numpy.core.umath', 'bitwise_xor', Parameters ---------- x1, x2 : array_like - Only integer types are handled (including booleans). + Only integer and boolean types are handled. Returns ------- @@ -766,7 +766,7 @@ add_newdoc('numpy.core.umath', 'conjugate', add_newdoc('numpy.core.umath', 'cos', """ - Cosine elementwise. + Cosine element-wise. Parameters ---------- @@ -937,8 +937,8 @@ add_newdoc('numpy.core.umath', 'divide', See Also -------- - seterr : Set whether to raise or warn on overflow, underflow and division - by zero. + seterr : Set whether to raise or warn on overflow, underflow and + division by zero. Notes ----- @@ -1048,8 +1048,8 @@ add_newdoc('numpy.core.umath', 'exp', For complex arguments, ``x = a + ib``, we can write :math:`e^x = e^a e^{ib}`. The first term, :math:`e^a`, is already known (it is the real argument, described above). The second term, - :math:`e^{ib}`, is :math:`\\cos b + i \\sin b`, a function with magnitude - 1 and a periodic phase. + :math:`e^{ib}`, is :math:`\\cos b + i \\sin b`, a function with + magnitude 1 and a periodic phase. References ---------- @@ -1137,7 +1137,7 @@ add_newdoc('numpy.core.umath', 'expm1', Notes ----- - This function provides greater precision than the formula ``exp(x) - 1`` + This function provides greater precision than ``exp(x) - 1`` for small values of ``x``. Examples @@ -1155,10 +1155,10 @@ add_newdoc('numpy.core.umath', 'expm1', add_newdoc('numpy.core.umath', 'fabs', """ - Compute the absolute values elementwise. + Compute the absolute values element-wise. - This function returns the absolute values (positive magnitude) of the data - in `x`. Complex values are not handled, use `absolute` to find the + This function returns the absolute values (positive magnitude) of the + data in `x`. Complex values are not handled, use `absolute` to find the absolute values of complex data. Parameters @@ -1212,8 +1212,8 @@ add_newdoc('numpy.core.umath', 'floor', Notes ----- Some spreadsheet programs calculate the "floor-towards-zero", in other - words ``floor(-2.5) == -2``. NumPy, however, uses the a definition of - `floor` such that `floor(-2.5) == -3`. + words ``floor(-2.5) == -2``. NumPy instead uses the definition of + `floor` where `floor(-2.5) == -3`. Examples -------- @@ -1225,7 +1225,8 @@ add_newdoc('numpy.core.umath', 'floor', add_newdoc('numpy.core.umath', 'floor_divide', """ - Return the largest integer smaller or equal to the division of the inputs. + Return the largest integer smaller or equal to the division of the + inputs. Parameters ---------- @@ -1259,7 +1260,10 @@ add_newdoc('numpy.core.umath', 'fmod', """ Return the element-wise remainder of division. - This is the NumPy implementation of the Python modulo operator `%`. + This is the NumPy implementation of the C library function fmod, the + remainder has the same sign as the dividend `x1`. It is equivalent to + the Matlab(TM) ``rem`` function and should not be confused with the + Python modulus operator ``x1 % x2``. Parameters ---------- @@ -1275,15 +1279,16 @@ add_newdoc('numpy.core.umath', 'fmod', See Also -------- - remainder : Modulo operation where the quotient is `floor(x1/x2)`. + remainder : Equivalent to the Python ``%`` operator. divide Notes ----- - The result of the modulo operation for negative dividend and divisors is - bound by conventions. In `fmod`, the sign of the remainder is the sign of - the dividend. In `remainder`, the sign of the divisor does not affect the - sign of the result. + The result of the modulo operation for negative dividend and divisors + is bound by conventions. For `fmod`, the sign of result is the sign of + the dividend, while for `remainder` the sign of the result is the sign + of the divisor. The `fmod` function is equivalent to the Matlab(TM) + ``rem`` function. Examples -------- @@ -1414,17 +1419,17 @@ add_newdoc('numpy.core.umath', 'invert', the integers in the input arrays. This ufunc implements the C/Python operator ``~``. - For signed integer inputs, the two's complement is returned. - In a two's-complement system negative numbers are represented by the two's + For signed integer inputs, the two's complement is returned. In a + two's-complement system negative numbers are represented by the two's complement of the absolute value. This is the most common method of - representing signed integers on computers [1]_. A N-bit two's-complement - system can represent every integer in the range + representing signed integers on computers [1]_. A N-bit + two's-complement system can represent every integer in the range :math:`-2^{N-1}` to :math:`+2^{N-1}-1`. Parameters ---------- x1 : array_like - Only integer types are handled (including booleans). + Only integer and boolean types are handled. Returns ------- @@ -1488,7 +1493,7 @@ add_newdoc('numpy.core.umath', 'invert', add_newdoc('numpy.core.umath', 'isfinite', """ - Test element-wise for finite-ness (not infinity or not Not a Number). + Test element-wise for finiteness (not infinity or not Not a Number). The result is returned as a boolean array. @@ -1508,9 +1513,10 @@ add_newdoc('numpy.core.umath', 'isfinite', either positive infinity, negative infinity or Not a Number). For array input, the result is a boolean array with the same - dimensions as the input and the values are True if the corresponding - element of the input is finite; otherwise the values are False (element - is either positive infinity, negative infinity or Not a Number). + dimensions as the input and the values are True if the + corresponding element of the input is finite; otherwise the values + are False (element is either positive infinity, negative infinity + or Not a Number). See Also -------- @@ -1524,9 +1530,9 @@ add_newdoc('numpy.core.umath', 'isfinite', Numpy uses the IEEE Standard for Binary Floating-Point for Arithmetic (IEEE 754). This means that Not a Number is not equivalent to infinity. Also that positive infinity is not equivalent to negative infinity. But - infinity is equivalent to positive infinity. - Errors result if the second argument is also supplied when `x` is a scalar - input, or if first and second arguments have different shapes. + infinity is equivalent to positive infinity. Errors result if the + second argument is also supplied when `x` is a scalar input, or if + first and second arguments have different shapes. Examples -------- @@ -1556,8 +1562,8 @@ add_newdoc('numpy.core.umath', 'isinf', """ Test element-wise for positive or negative infinity. - Return a bool-type array, the same shape as `x`, True where ``x == - +/-inf``, False everywhere else. + Returns a boolean array of the same shape as `x`, True where ``x == + +/-inf``, otherwise False. Parameters ---------- @@ -1568,19 +1574,19 @@ add_newdoc('numpy.core.umath', 'isinf', Returns ------- - y : bool (scalar) or bool-type ndarray - For scalar input, the result is a new boolean with value True - if the input is positive or negative infinity; otherwise the value - is False. + y : bool (scalar) or boolean ndarray + For scalar input, the result is a new boolean with value True if + the input is positive or negative infinity; otherwise the value is + False. - For array input, the result is a boolean array with the same - shape as the input and the values are True where the - corresponding element of the input is positive or negative - infinity; elsewhere the values are False. If a second argument - was supplied the result is stored there. If the type of that array - is a numeric type the result is represented as zeros and ones, if - the type is boolean then as False and True, respectively. - The return value `y` is then a reference to that array. + For array input, the result is a boolean array with the same shape + as the input and the values are True where the corresponding + element of the input is positive or negative infinity; elsewhere + the values are False. If a second argument was supplied the result + is stored there. If the type of that array is a numeric type the + result is represented as zeros and ones, if the type is boolean + then as False and True, respectively. The return value `y` is then + a reference to that array. See Also -------- @@ -1617,7 +1623,7 @@ add_newdoc('numpy.core.umath', 'isinf', add_newdoc('numpy.core.umath', 'isnan', """ - Test element-wise for Not a Number (NaN), return result as a bool array. + Test element-wise for NaN and return result as a boolean array. Parameters ---------- @@ -1627,12 +1633,13 @@ add_newdoc('numpy.core.umath', 'isnan', Returns ------- y : {ndarray, bool} - For scalar input, the result is a new boolean with value True - if the input is NaN; otherwise the value is False. + For scalar input, the result is a new boolean with value True if + the input is NaN; otherwise the value is False. - For array input, the result is a boolean array with the same - dimensions as the input and the values are True if the corresponding - element of the input is NaN; otherwise the values are False. + For array input, the result is a boolean array of the same + dimensions as the input and the values are True if the + corresponding element of the input is NaN; otherwise the values are + False. See Also -------- @@ -1753,7 +1760,8 @@ add_newdoc('numpy.core.umath', 'log', Natural logarithm, element-wise. The natural logarithm `log` is the inverse of the exponential function, - so that `log(exp(x)) = x`. The natural logarithm is logarithm in base `e`. + so that `log(exp(x)) = x`. The natural logarithm is logarithm in base + `e`. Parameters ---------- @@ -1772,8 +1780,8 @@ add_newdoc('numpy.core.umath', 'log', Notes ----- Logarithm is a multivalued function: for each `x` there is an infinite - number of `z` such that `exp(z) = x`. The convention is to return the `z` - whose imaginary part lies in `[-pi, pi]`. + number of `z` such that `exp(z) = x`. The convention is to return the + `z` whose imaginary part lies in `[-pi, pi]`. For real-valued input data types, `log` always returns real output. For each value that cannot be expressed as a real number or infinity, it @@ -1819,17 +1827,17 @@ add_newdoc('numpy.core.umath', 'log10', Notes ----- Logarithm is a multivalued function: for each `x` there is an infinite - number of `z` such that `10**z = x`. The convention is to return the `z` - whose imaginary part lies in `[-pi, pi]`. + number of `z` such that `10**z = x`. The convention is to return the + `z` whose imaginary part lies in `[-pi, pi]`. - For real-valued input data types, `log10` always returns real output. For - each value that cannot be expressed as a real number or infinity, it - yields ``nan`` and sets the `invalid` floating point error flag. + For real-valued input data types, `log10` always returns real output. + For each value that cannot be expressed as a real number or infinity, + it yields ``nan`` and sets the `invalid` floating point error flag. For complex-valued input, `log10` is a complex analytical function that - has a branch cut `[-inf, 0]` and is continuous from above on it. `log10` - handles the floating-point negative zero as an infinitesimal negative - number, conforming to the C99 standard. + has a branch cut `[-inf, 0]` and is continuous from above on it. + `log10` handles the floating-point negative zero as an infinitesimal + negative number, conforming to the C99 standard. References ---------- @@ -1870,9 +1878,9 @@ add_newdoc('numpy.core.umath', 'log2', number of `z` such that `2**z = x`. The convention is to return the `z` whose imaginary part lies in `[-pi, pi]`. - For real-valued input data types, `log2` always returns real output. For - each value that cannot be expressed as a real number or infinity, it - yields ``nan`` and sets the `invalid` floating point error flag. + For real-valued input data types, `log2` always returns real output. + For each value that cannot be expressed as a real number or infinity, + it yields ``nan`` and sets the `invalid` floating point error flag. For complex-valued input, `log2` is a complex analytical function that has a branch cut `[-inf, 0]` and is continuous from above on it. `log2` @@ -1913,7 +1921,7 @@ add_newdoc('numpy.core.umath', 'logaddexp', See Also -------- - logaddexp2: Logarithm of the sum of exponentiations of inputs in base-2. + logaddexp2: Logarithm of the sum of exponentiations of inputs in base 2. Notes ----- @@ -1936,8 +1944,8 @@ add_newdoc('numpy.core.umath', 'logaddexp2', Logarithm of the sum of exponentiations of the inputs in base-2. Calculates ``log2(2**x1 + 2**x2)``. This function is useful in machine - learning when the calculated probabilities of events may be so small - as to exceed the range of normal floating point numbers. In such cases + learning when the calculated probabilities of events may be so small as + to exceed the range of normal floating point numbers. In such cases the base-2 logarithm of the calculated probability can be used instead. This function allows adding probabilities stored in such a fashion. @@ -2002,14 +2010,14 @@ add_newdoc('numpy.core.umath', 'log1p', number of `z` such that `exp(z) = 1 + x`. The convention is to return the `z` whose imaginary part lies in `[-pi, pi]`. - For real-valued input data types, `log1p` always returns real output. For - each value that cannot be expressed as a real number or infinity, it - yields ``nan`` and sets the `invalid` floating point error flag. + For real-valued input data types, `log1p` always returns real output. + For each value that cannot be expressed as a real number or infinity, + it yields ``nan`` and sets the `invalid` floating point error flag. For complex-valued input, `log1p` is a complex analytical function that - has a branch cut `[-inf, -1]` and is continuous from above on it. `log1p` - handles the floating-point negative zero as an infinitesimal negative - number, conforming to the C99 standard. + has a branch cut `[-inf, -1]` and is continuous from above on it. + `log1p` handles the floating-point negative zero as an infinitesimal + negative number, conforming to the C99 standard. References ---------- @@ -2028,7 +2036,7 @@ add_newdoc('numpy.core.umath', 'log1p', add_newdoc('numpy.core.umath', 'logical_and', """ - Compute the truth value of x1 AND x2 elementwise. + Compute the truth value of x1 AND x2 element-wise. Parameters ---------- @@ -2062,7 +2070,7 @@ add_newdoc('numpy.core.umath', 'logical_and', add_newdoc('numpy.core.umath', 'logical_not', """ - Compute the truth value of NOT x elementwise. + Compute the truth value of NOT x element-wise. Parameters ---------- @@ -2094,7 +2102,7 @@ add_newdoc('numpy.core.umath', 'logical_not', add_newdoc('numpy.core.umath', 'logical_or', """ - Compute the truth value of x1 OR x2 elementwise. + Compute the truth value of x1 OR x2 element-wise. Parameters ---------- @@ -2171,11 +2179,11 @@ add_newdoc('numpy.core.umath', 'maximum', Element-wise maximum of array elements. Compare two arrays and returns a new array containing the element-wise - maxima. If one of the elements being compared is a nan, then that element - is returned. If both elements are nans then the first is returned. The - latter distinction is important for complex nans, which are defined as at - least one of the real or imaginary parts being a nan. The net effect is - that nans are propagated. + maxima. If one of the elements being compared is a NaN, then that + element is returned. If both elements are NaNs then the first is + returned. The latter distinction is important for complex NaNs, which + are defined as at least one of the real or imaginary parts being a NaN. + The net effect is that NaNs are propagated. Parameters ---------- @@ -2192,20 +2200,21 @@ add_newdoc('numpy.core.umath', 'maximum', See Also -------- minimum : - Element-wise minimum of two arrays, propagating any NaNs. + Element-wise minimum of two arrays, propagates NaNs. fmax : - Element-wise maximum of two arrays, ignoring any NaNs. + Element-wise maximum of two arrays, ignores NaNs. amax : - The maximum value of an array along a given axis, propagating any NaNs. + The maximum value of an array along a given axis, propagates NaNs. nanmax : - The maximum value of an array along a given axis, ignoring any NaNs. + The maximum value of an array along a given axis, ignores NaNs. fmin, amin, nanmin Notes ----- - The maximum is equivalent to ``np.where(x1 >= x2, x1, x2)`` when neither - x1 nor x2 are nans, but it is faster and does proper broadcasting. + The maximum is equivalent to ``np.where(x1 >= x2, x1, x2)`` when + neither x1 nor x2 are nans, but it is faster and does proper + broadcasting. Examples -------- @@ -2228,11 +2237,11 @@ add_newdoc('numpy.core.umath', 'minimum', Element-wise minimum of array elements. Compare two arrays and returns a new array containing the element-wise - minima. If one of the elements being compared is a nan, then that element - is returned. If both elements are nans then the first is returned. The - latter distinction is important for complex nans, which are defined as at - least one of the real or imaginary parts being a nan. The net effect is - that nans are propagated. + minima. If one of the elements being compared is a NaN, then that + element is returned. If both elements are NaNs then the first is + returned. The latter distinction is important for complex NaNs, which + are defined as at least one of the real or imaginary parts being a NaN. + The net effect is that NaNs are propagated. Parameters ---------- @@ -2249,20 +2258,21 @@ add_newdoc('numpy.core.umath', 'minimum', See Also -------- maximum : - Element-wise maximum of two arrays, propagating any NaNs. + Element-wise maximum of two arrays, propagates NaNs. fmin : - Element-wise minimum of two arrays, ignoring any NaNs. + Element-wise minimum of two arrays, ignores NaNs. amin : - The minimum value of an array along a given axis, propagating any NaNs. + The minimum value of an array along a given axis, propagates NaNs. nanmin : - The minimum value of an array along a given axis, ignoring any NaNs. + The minimum value of an array along a given axis, ignores NaNs. fmax, amax, nanmax Notes ----- - The minimum is equivalent to ``np.where(x1 <= x2, x1, x2)`` when neither - x1 nor x2 are nans, but it is faster and does proper broadcasting. + The minimum is equivalent to ``np.where(x1 <= x2, x1, x2)`` when + neither x1 nor x2 are NaNs, but it is faster and does proper + broadcasting. Examples -------- @@ -2285,11 +2295,11 @@ add_newdoc('numpy.core.umath', 'fmax', Element-wise maximum of array elements. Compare two arrays and returns a new array containing the element-wise - maxima. If one of the elements being compared is a nan, then the non-nan - element is returned. If both elements are nans then the first is returned. - The latter distinction is important for complex nans, which are defined as - at least one of the real or imaginary parts being a nan. The net effect is - that nans are ignored when possible. + maxima. If one of the elements being compared is a NaN, then the + non-nan element is returned. If both elements are NaNs then the first + is returned. The latter distinction is important for complex NaNs, + which are defined as at least one of the real or imaginary parts being + a NaN. The net effect is that NaNs are ignored when possible. Parameters ---------- @@ -2306,13 +2316,13 @@ add_newdoc('numpy.core.umath', 'fmax', See Also -------- fmin : - Element-wise minimum of two arrays, ignoring any NaNs. + Element-wise minimum of two arrays, ignores NaNs. maximum : - Element-wise maximum of two arrays, propagating any NaNs. + Element-wise maximum of two arrays, propagates NaNs. amax : - The maximum value of an array along a given axis, propagating any NaNs. + The maximum value of an array along a given axis, propagates NaNs. nanmax : - The maximum value of an array along a given axis, ignoring any NaNs. + The maximum value of an array along a given axis, ignores NaNs. minimum, amin, nanmin @@ -2321,7 +2331,7 @@ add_newdoc('numpy.core.umath', 'fmax', .. versionadded:: 1.3.0 The fmax is equivalent to ``np.where(x1 >= x2, x1, x2)`` when neither - x1 nor x2 are nans, but it is faster and does proper broadcasting. + x1 nor x2 are NaNs, but it is faster and does proper broadcasting. Examples -------- @@ -2342,11 +2352,11 @@ add_newdoc('numpy.core.umath', 'fmin', Element-wise minimum of array elements. Compare two arrays and returns a new array containing the element-wise - minima. If one of the elements being compared is a nan, then the non-nan - element is returned. If both elements are nans then the first is returned. - The latter distinction is important for complex nans, which are defined as - at least one of the real or imaginary parts being a nan. The net effect is - that nans are ignored when possible. + minima. If one of the elements being compared is a NaN, then the + non-nan element is returned. If both elements are NaNs then the first + is returned. The latter distinction is important for complex NaNs, + which are defined as at least one of the real or imaginary parts being + a NaN. The net effect is that NaNs are ignored when possible. Parameters ---------- @@ -2363,13 +2373,13 @@ add_newdoc('numpy.core.umath', 'fmin', See Also -------- fmax : - Element-wise maximum of two arrays, ignoring any NaNs. + Element-wise maximum of two arrays, ignores NaNs. minimum : - Element-wise minimum of two arrays, propagating any NaNs. + Element-wise minimum of two arrays, propagates NaNs. amin : - The minimum value of an array along a given axis, propagating any NaNs. + The minimum value of an array along a given axis, propagates NaNs. nanmin : - The minimum value of an array along a given axis, ignoring any NaNs. + The minimum value of an array along a given axis, ignores NaNs. maximum, amax, nanmax @@ -2378,7 +2388,7 @@ add_newdoc('numpy.core.umath', 'fmin', .. versionadded:: 1.3.0 The fmin is equivalent to ``np.where(x1 <= x2, x1, x2)`` when neither - x1 nor x2 are nans, but it is faster and does proper broadcasting. + x1 nor x2 are NaNs, but it is faster and does proper broadcasting. Examples -------- @@ -2461,7 +2471,7 @@ add_newdoc('numpy.core.umath', 'multiply', add_newdoc('numpy.core.umath', 'negative', """ - Returns an array with the negative of each element of the original array. + Numerical negative, element-wise. Parameters ---------- @@ -2515,10 +2525,9 @@ add_newdoc('numpy.core.umath', 'not_equal', add_newdoc('numpy.core.umath', '_ones_like', """ - This function used to be the numpy.ones_like, but now a - specific function for that has been written for consistency with - the other *_like functions. It is only used internally in a limited - fashion now. + This function used to be the numpy.ones_like, but now a specific + function for that has been written for consistency with the other + *_like functions. It is only used internally in a limited fashion now. See Also -------- @@ -2664,8 +2673,8 @@ add_newdoc('numpy.core.umath', 'reciprocal', This function is not designed to work with integers. For integer arguments with absolute value larger than 1 the result is - always zero because of the way Python handles integer division. - For integer zero the result is an overflow. + always zero because of the way Python handles integer division. For + integer zero the result is an overflow. Examples -------- @@ -2680,7 +2689,10 @@ add_newdoc('numpy.core.umath', 'remainder', """ Return element-wise remainder of division. - Computes ``x1 - floor(x1 / x2) * x2``. + Computes ``x1 - floor(x1 / x2) * x2``, the result has the same sign as + the divisor `x2`. It is equivalent to the Python modulus operator + ``x1 % x2`` and should not be confused with the Matlab(TM) ``rem`` + function. Parameters ---------- @@ -2695,16 +2707,18 @@ add_newdoc('numpy.core.umath', 'remainder', Returns ------- y : ndarray - The remainder of the quotient ``x1/x2``, element-wise. Returns a scalar - if both `x1` and `x2` are scalars. + The remainder of the quotient ``x1/x2``, element-wise. Returns a + scalar if both `x1` and `x2` are scalars. See Also -------- + fmod : Equivalent of the Matlab(TM) ``rem`` function. divide, floor Notes ----- - Returns 0 when `x2` is 0 and both `x1` and `x2` are (arrays of) integers. + Returns 0 when `x2` is 0 and both `x1` and `x2` are (arrays of) + integers. Examples -------- @@ -2719,9 +2733,9 @@ add_newdoc('numpy.core.umath', 'right_shift', """ Shift the bits of an integer to the right. - Bits are shifted to the right by removing `x2` bits at the right of `x1`. - Since the internal representation of numbers is in binary format, this - operation is equivalent to dividing `x1` by ``2**x2``. + Bits are shifted to the right `x2`. Because the internal + representation of numbers is in binary format, this operation is + equivalent to dividing `x1` by ``2**x2``. Parameters ---------- @@ -2815,9 +2829,8 @@ add_newdoc('numpy.core.umath', 'signbit', x : array_like The input value(s). out : ndarray, optional - Array into which the output is placed. Its type is preserved - and it must be of the right shape to hold the output. - See `doc.ufuncs`. + Array into which the output is placed. Its type is preserved and it + must be of the right shape to hold the output. See `doc.ufuncs`. Returns ------- @@ -2874,8 +2887,7 @@ add_newdoc('numpy.core.umath', 'copysign', add_newdoc('numpy.core.umath', 'nextafter', """ - Return the next representable floating-point value after x1 in the direction - of x2 element-wise. + Return the next floating-point value after x1 towards x2, element-wise. Parameters ---------- @@ -2923,7 +2935,7 @@ add_newdoc('numpy.core.umath', 'spacing', should not be any representable number between ``x + spacing(x)`` and x for any finite x. - Spacing of +- inf and nan is nan. + Spacing of +- inf and NaN is NaN. Examples -------- @@ -2952,17 +2964,17 @@ add_newdoc('numpy.core.umath', 'sin', Notes ----- - The sine is one of the fundamental functions of trigonometry - (the mathematical study of triangles). Consider a circle of radius - 1 centered on the origin. A ray comes in from the :math:`+x` axis, - makes an angle at the origin (measured counter-clockwise from that - axis), and departs from the origin. The :math:`y` coordinate of - the outgoing ray's intersection with the unit circle is the sine - of that angle. It ranges from -1 for :math:`x=3\\pi / 2` to - +1 for :math:`\\pi / 2.` The function has zeroes where the angle is - a multiple of :math:`\\pi`. Sines of angles between :math:`\\pi` and - :math:`2\\pi` are negative. The numerous properties of the sine and - related functions are included in any standard trigonometry text. + The sine is one of the fundamental functions of trigonometry (the + mathematical study of triangles). Consider a circle of radius 1 + centered on the origin. A ray comes in from the :math:`+x` axis, makes + an angle at the origin (measured counter-clockwise from that axis), and + departs from the origin. The :math:`y` coordinate of the outgoing + ray's intersection with the unit circle is the sine of that angle. It + ranges from -1 for :math:`x=3\\pi / 2` to +1 for :math:`\\pi / 2.` The + function has zeroes where the angle is a multiple of :math:`\\pi`. + Sines of angles between :math:`\\pi` and :math:`2\\pi` are negative. + The numerous properties of the sine and related functions are included + in any standard trigonometry text. Examples -------- @@ -3076,8 +3088,8 @@ add_newdoc('numpy.core.umath', 'sqrt', ----- *sqrt* has--consistent with common convention--as its branch cut the real "interval" [`-inf`, 0), and is continuous from above on it. - (A branch cut is a curve in the complex plane across which a given - complex function fails to be continuous.) + A branch cut is a curve in the complex plane across which a given + complex function fails to be continuous. Examples -------- @@ -3210,8 +3222,7 @@ add_newdoc('numpy.core.umath', 'tanh', """ Compute hyperbolic tangent element-wise. - Equivalent to ``np.sinh(x)/np.cosh(x)`` or - ``-1j * np.tan(1j*x)``. + Equivalent to ``np.sinh(x)/np.cosh(x)`` or ``-1j * np.tan(1j*x)``. Parameters ---------- @@ -3285,10 +3296,10 @@ add_newdoc('numpy.core.umath', 'true_divide', Notes ----- - The floor division operator ``//`` was added in Python 2.2 making ``//`` - and ``/`` equivalent operators. The default floor division operation of - ``/`` can be replaced by true division with - ``from __future__ import division``. + The floor division operator ``//`` was added in Python 2.2 making + ``//`` and ``/`` equivalent operators. The default floor division + operation of ``/`` can be replaced by true division with ``from + __future__ import division``. In Python 3.0, ``//`` is the floor division operator and ``/`` the true division operator. The ``true_divide(x1, x2)`` function is @@ -3312,3 +3323,97 @@ add_newdoc('numpy.core.umath', 'true_divide', array([0, 0, 0, 0, 1]) """) + +# This doc is not currently used, but has been converted to a C string +# that can be found in numpy/core/src/umath/umathmodule.c where the +# frexp ufunc is constructed. +add_newdoc('numpy.core.umath', 'frexp', + """ + Decompose the elements of x into mantissa and twos exponent. + + Returns (`mantissa`, `exponent`), where `x = mantissa * 2**exponent``. + The mantissa is lies in the open interval(-1, 1), while the twos + exponent is a signed integer. + + Parameters + ---------- + x : array_like + Array of numbers to be decomposed. + out1: ndarray, optional + Output array for the mantissa. Must have the same shape as `x`. + out2: ndarray, optional + Output array for the exponent. Must have the same shape as `x`. + + Returns + ------- + (mantissa, exponent) : tuple of ndarrays, (float, int) + `mantissa` is a float array with values between -1 and 1. + `exponent` is an int array which represents the exponent of 2. + + See Also + -------- + ldexp : Compute ``y = x1 * 2**x2``, the inverse of `frexp`. + + Notes + ----- + Complex dtypes are not supported, they will raise a TypeError. + + Examples + -------- + >>> x = np.arange(9) + >>> y1, y2 = np.frexp(x) + >>> y1 + array([ 0. , 0.5 , 0.5 , 0.75 , 0.5 , 0.625, 0.75 , 0.875, + 0.5 ]) + >>> y2 + array([0, 1, 2, 2, 3, 3, 3, 3, 4]) + >>> y1 * 2**y2 + array([ 0., 1., 2., 3., 4., 5., 6., 7., 8.]) + + """) + +# This doc is not currently used, but has been converted to a C string +# that can be found in numpy/core/src/umath/umathmodule.c where the +# ldexp ufunc is constructed. +add_newdoc('numpy.core.umath', 'ldexp', + """ + Returns x1 * 2**x2, element-wise. + + The mantissas `x1` and twos exponents `x2` are used to construct + floating point numbers ``x1 * 2**x2``. + + Parameters + ---------- + x1 : array_like + Array of multipliers. + x2 : array_like, int + Array of twos exponents. + out : ndarray, optional + Output array for the result. + + Returns + ------- + y : ndarray or scalar + The result of ``x1 * 2**x2``. + + See Also + -------- + frexp : Return (y1, y2) from ``x = y1 * 2**y2``, inverse to `ldexp`. + + Notes + ----- + Complex dtypes are not supported, they will raise a TypeError. + + `ldexp` is useful as the inverse of `frexp`, if used by itself it is + more clear to simply use the expression ``x1 * 2**x2``. + + Examples + -------- + >>> np.ldexp(5, np.arange(4)) + array([ 5., 10., 20., 40.], dtype=float32) + + >>> x = np.arange(6) + >>> np.ldexp(*np.frexp(x)) + array([ 0., 1., 2., 3., 4., 5.]) + + """) diff --git a/numpy/core/src/umath/umathmodule.c b/numpy/core/src/umath/umathmodule.c index f395d5096..b1fc2f7be 100644 --- a/numpy/core/src/umath/umathmodule.c +++ b/numpy/core/src/umath/umathmodule.c @@ -251,6 +251,50 @@ static PyUFuncGenericFunction ldexp_functions[] = { #endif }; +static const char frdoc[] = + " Decompose the elements of x into mantissa and twos exponent.\n" + "\n" + " Returns (`mantissa`, `exponent`), where `x = mantissa * 2**exponent``.\n" + " The mantissa is lies in the open interval(-1, 1), while the twos\n" + " exponent is a signed integer.\n" + "\n" + " Parameters\n" + " ----------\n" + " x : array_like\n" + " Array of numbers to be decomposed.\n" + " out1: ndarray, optional\n" + " Output array for the mantissa. Must have the same shape as `x`.\n" + " out2: ndarray, optional\n" + " Output array for the exponent. Must have the same shape as `x`.\n" + "\n" + " Returns\n" + " -------\n" + " (mantissa, exponent) : tuple of ndarrays, (float, int)\n" + " `mantissa` is a float array with values between -1 and 1.\n" + " `exponent` is an int array which represents the exponent of 2.\n" + "\n" + " See Also\n" + " --------\n" + " ldexp : Compute ``y = x1 * 2**x2``, the inverse of `frexp`.\n" + "\n" + " Notes\n" + " -----\n" + " Complex dtypes are not supported, they will raise a TypeError.\n" + "\n" + " Examples\n" + " --------\n" + " >>> x = np.arange(9)\n" + " >>> y1, y2 = np.frexp(x)\n" + " >>> y1\n" + " array([ 0. , 0.5 , 0.5 , 0.75 , 0.5 , 0.625, 0.75 , 0.875,\n" + " 0.5 ])\n" + " >>> y2\n" + " array([0, 1, 2, 2, 3, 3, 3, 3, 4])\n" + " >>> y1 * 2**y2\n" + " array([ 0., 1., 2., 3., 4., 5., 6., 7., 8.])\n" + "\n"; + + static char ldexp_signatures[] = { #ifdef HAVE_LDEXPF NPY_HALF, NPY_INT, NPY_HALF, @@ -266,6 +310,48 @@ static char ldexp_signatures[] = { #endif }; +static const char lddoc[] = + " Returns x1 * 2**x2, element-wise.\n" + "\n" + " The mantissas `x1` and twos exponents `x2` are used to construct\n" + " floating point numbers ``x1 * 2**x2``.\n" + "\n" + " Parameters\n" + " ----------\n" + " x1 : array_like\n" + " Array of multipliers.\n" + " x2 : array_like, int\n" + " Array of twos exponents.\n" + " out : ndarray, optional\n" + " Output array for the result.\n" + "\n" + " Returns\n" + " -------\n" + " y : ndarray or scalar\n" + " The result of ``x1 * 2**x2``.\n" + "\n" + " See Also\n" + " --------\n" + " frexp : Return (y1, y2) from ``x = y1 * 2**y2``, inverse to `ldexp`.\n" + "\n" + " Notes\n" + " -----\n" + " Complex dtypes are not supported, they will raise a TypeError.\n" + "\n" + " `ldexp` is useful as the inverse of `frexp`, if used by itself it is\n" + " more clear to simply use the expression ``x1 * 2**x2``.\n" + "\n" + " Examples\n" + " --------\n" + " >>> np.ldexp(5, np.arange(4))\n" + " array([ 5., 10., 20., 40.], dtype=float32)\n" + "\n" + " >>> x = np.arange(6)\n" + " >>> np.ldexp(*np.frexp(x))\n" + " array([ 0., 1., 2., 3., 4., 5.])\n" + "\n"; + + static void InitOtherOperators(PyObject *dictionary) { PyObject *f; @@ -274,16 +360,14 @@ InitOtherOperators(PyObject *dictionary) { num = sizeof(frexp_functions) / sizeof(frexp_functions[0]); f = PyUFunc_FromFuncAndData(frexp_functions, blank3_data, frexp_signatures, num, - 1, 2, PyUFunc_None, "frexp", - "Split the number, x, into a normalized"\ - " fraction (y1) and exponent (y2)",0); + 1, 2, PyUFunc_None, "frexp", frdoc, 0); PyDict_SetItemString(dictionary, "frexp", f); Py_DECREF(f); num = sizeof(ldexp_functions) / sizeof(ldexp_functions[0]); - f = PyUFunc_FromFuncAndData(ldexp_functions, blank6_data, ldexp_signatures, num, - 2, 1, PyUFunc_None, "ldexp", - "Compute y = x1 * 2**x2.",0); + f = PyUFunc_FromFuncAndData(ldexp_functions, blank6_data, + ldexp_signatures, num, + 2, 1, PyUFunc_None, "ldexp", lddoc, 0); PyDict_SetItemString(dictionary, "ldexp", f); Py_DECREF(f); |