diff options
| -rw-r--r-- | numpy/core/code_generators/ufunc_docstrings.py | 296 |
1 files changed, 165 insertions, 131 deletions
diff --git a/numpy/core/code_generators/ufunc_docstrings.py b/numpy/core/code_generators/ufunc_docstrings.py index c63df7c8f..0cb3a423a 100644 --- a/numpy/core/code_generators/ufunc_docstrings.py +++ b/numpy/core/code_generators/ufunc_docstrings.py @@ -20,7 +20,7 @@ add_newdoc('numpy.core.umath', 'absolute', Returns ------- - res : ndarray + absolute : ndarray An ndarray containing the absolute value of each element in `x`. For complex input, ``a + ib``, the absolute value is :math:`\\sqrt{ a^2 + b^2 }`. @@ -56,12 +56,14 @@ add_newdoc('numpy.core.umath', 'add', Parameters ---------- x1, x2 : array_like - The arrays to be added. + The arrays to be added. If ``x1.shape != x2.shape``, they must be + broadcastable to a common shape (which may be the shape of one or + the other). Returns ------- - y : {ndarray, scalar} - The sum of `x1` and `x2`, element-wise. Returns scalar if + y : ndarray or scalar + The sum of `x1` and `x2`, element-wise. Returns a scalar if both `x1` and `x2` are scalars. Notes @@ -112,25 +114,23 @@ add_newdoc('numpy.core.umath', 'arccos', Notes ----- `arccos` is a multivalued function: for each `x` there are infinitely - many numbers `z` such that `cos(z) = x`. The convention is to return the - angle `z` whose real part lies in `[0, pi]`. + many numbers `z` such that `cos(z) = x`. The convention is to return + the angle `z` whose real part lies in `[0, pi]`. For real-valued input data types, `arccos` 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, `arccos` is a complex analytical function that - has branch cuts `[-inf, -1]` and `[1, inf]` and is continuous from above - on the former and from below on the latter. + For complex-valued input, `arccos` is a complex analytic function that + has branch cuts `[-inf, -1]` and `[1, inf]` and is continuous from + above on the former and from below on the latter. The inverse `cos` is also known as `acos` or cos^-1. References ---------- - .. [1] M. Abramowitz and I.A. Stegun, "Handbook of Mathematical Functions", - 10th printing, 1964, pp. 79. http://www.math.sfu.ca/~cbm/aands/ - .. [2] Wikipedia, "Inverse trigonometric function", - http://en.wikipedia.org/wiki/Inverse_trigonometric_function + M. Abramowitz and I.A. Stegun, "Handbook of Mathematical Functions", + 10th printing, 1964, pp. 79. http://www.math.sfu.ca/~cbm/aands/ Examples -------- @@ -204,23 +204,23 @@ add_newdoc('numpy.core.umath', 'arccosh', add_newdoc('numpy.core.umath', 'arcsin', """ - Inverse sine elementwise. + Inverse sine, element-wise. Parameters ---------- x : array_like - `y`-coordinate on the unit circle. + `y`-coordinate on the unit circle. out : ndarray, optional - Array of the same shape as `x`, to store results in. See - `doc.ufuncs` (Section "Output arguments") for more details. + Array of the same shape as `x`, in which to store the results. + See `doc.ufuncs` (Section "Output arguments") for more details. Returns ------- angle : ndarray - The angle of the ray intersecting the unit circle at the given - `y`-coordinate in radians ``[-pi, pi]``. If `x` is a scalar then - a scalar is returned, otherwise an array is returned. + The inverse sine of each element in `x`, in radians and in the + closed interval ``[-pi/2, pi/2]``. If `x` is a scalar, a scalar + is returned, otherwise an array. See Also -------- @@ -229,25 +229,24 @@ add_newdoc('numpy.core.umath', 'arcsin', Notes ----- `arcsin` is a multivalued function: for each `x` there are infinitely - many numbers `z` such that `sin(z) = x`. The convention is to return the - angle `z` whose real part lies in `[-pi/2, pi/2]`. + many numbers `z` such that :math:`sin(z) = x`. The convention is to + return the angle `z` whose real part lies in [-pi/2, pi/2]. - For real-valued input data types, `arcsin` 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, *arcsin* 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, `arcsin` is a complex analytical function that - has branch cuts `[-inf, -1]` and `[1, inf]` and is continuous from above - on the former and from below on the latter. + For complex-valued input, `arcsin` is a complex analytic function that + has, by convention, the branch cuts [-inf, -1] and [1, inf] and is + continuous from above on the former and from below on the latter. - The inverse sine is also known as `asin` or ``sin^-1``. + The inverse sine is also known as `asin` or sin^{-1}. References ---------- - .. [1] M. Abramowitz and I.A. Stegun, "Handbook of Mathematical Functions", - 10th printing, 1964, pp. 79. http://www.math.sfu.ca/~cbm/aands/ - .. [2] Wikipedia, "Inverse trigonometric function", - http://en.wikipedia.org/wiki/Inverse_trigonometric_function + Abramowitz, M. and Stegun, I. A., *Handbook of Mathematical Functions*, + 10th printing, New York: Dover, 1964, pp. 79ff. + http://www.math.sfu.ca/~cbm/aands/ Examples -------- @@ -311,8 +310,7 @@ add_newdoc('numpy.core.umath', 'arctan', """ Trigonometric inverse tangent, element-wise. - The inverse of tan, so that if ``y = tan(x)`` then - ``x = arctan(y)``. + The inverse of tan, so that if ``y = tan(x)`` then ``x = arctan(y)``. Parameters ---------- @@ -322,39 +320,41 @@ add_newdoc('numpy.core.umath', 'arctan', Returns ------- out : ndarray - Out has the same shape as `x`. Its real part is - in ``[-pi/2, pi/2]``. It is a scalar if `x` is a scalar. + Out has the same shape as `x`. Its real part is in + ``[-pi/2, pi/2]`` (``arctan(+/-inf)`` returns ``+/-pi/2``). + It is a scalar if `x` is a scalar. See Also -------- - arctan2 : Calculate the arctan of y/x. + arctan2 : The "four quadrant" arctan of the angle formed by (`x`, `y`) + and the positive `x`-axis. + angle : Argument of complex values. Notes ----- - `arctan` is a multivalued function: for each `x` there are infinitely - many numbers `z` such that `tan(z) = x`. The convention is to return the - angle `z` whose real part lies in `[-pi/2, pi/2]`. + `arctan` is a multi-valued function: for each `x` there are infinitely + many numbers `z` such that tan(`z`) = `x`. The convention is to return + the angle `z` whose real part lies in [-pi/2, pi/2]. For real-valued input data types, `arctan` 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, `arctan` is a complex analytical function that - has branch cuts `[1j, infj]` and `[-1j, -infj]` and is continuous from the - left on the former and from the right on the latter. + For complex-valued input, `arctan` is a complex analytic function that + has [`1j, infj`] and [`-1j, -infj`] as branch cuts, and is continuous + from the left on the former and from the right on the latter. - The inverse tangent is also known as `atan` or ``tan^-1``. + The inverse tangent is also known as `atan` or tan^{-1}. References ---------- - .. [1] M. Abramowitz and I.A. Stegun, "Handbook of Mathematical Functions", - 10th printing, 1964, pp. 79. http://www.math.sfu.ca/~cbm/aands/ - .. [2] Wikipedia, "Inverse trigonometric function", - http://en.wikipedia.org/wiki/Arctan + Abramowitz, M. and Stegun, I. A., *Handbook of Mathematical Functions*, + 10th printing, New York: Dover, 1964, pp. 79. + http://www.math.sfu.ca/~cbm/aands/ Examples -------- - We expect the arctan of 0 to be 0, and of 1 to be :math:`\\pi/4`: + We expect the arctan of 0 to be 0, and of 1 to be pi/4: >>> np.arctan([0, 1]) array([ 0. , 0.78539816]) @@ -374,22 +374,27 @@ add_newdoc('numpy.core.umath', 'arctan', add_newdoc('numpy.core.umath', 'arctan2', """ - Elementwise arc tangent of ``x1/x2`` choosing the quadrant correctly. + Element-wise arc tangent of ``x1/x2`` choosing the quadrant correctly. - The quadrant (ie. branch) is chosen so that ``arctan2(x1, x2)`` - is the signed angle in radians between the line segments - ``(0,0) - (1,0)`` and ``(0,0) - (x2,x1)``. This function is defined - also for `x2` = 0. + The quadrant (i.e., branch) is chosen so that ``arctan2(x1, x2)`` is + the signed angle in radians between the ray ending at the origin and + passing through the point (1,0), and the ray ending at the origin and + passing through the point (`x2`, `x1`). (Note the role reversal: the + "`y`-coordinate" is the first function parameter, the "`x`-coordinate" + is the second.) By IEEE convention, this function is defined for + `x2` = +/-0 and for either or both of `x1` and `x2` = +/-inf (see + Notes for specific values). - `arctan2` is not defined for complex-valued arguments. + This function is not defined for complex-valued arguments; for the + so-called argument of complex values, use `angle`. Parameters ---------- x1 : array_like, real-valued - y-coordinates. + `y`-coordinates. x2 : array_like, real-valued - x-coordinates. `x2` must be broadcastable to match the shape of `x1`, - or vice versa. + `x`-coordinates. `x2` must be broadcastable to match the shape of + `x1` or vice versa. Returns ------- @@ -398,12 +403,13 @@ add_newdoc('numpy.core.umath', 'arctan2', See Also -------- - arctan, tan + arctan, tan, angle Notes ----- - `arctan2` is identical to the `atan2` function of the underlying - C library. The following special values are defined in the C standard [2]: + *arctan2* is identical to the `atan2` function of the underlying + C library. The following special values are defined in the C + standard: [1]_ ====== ====== ================ `x1` `x2` `arctan2(x1,x2)` @@ -416,13 +422,12 @@ add_newdoc('numpy.core.umath', 'arctan2', +/-inf -inf +/- (3*pi/4) ====== ====== ================ - Note that +0 and -0 are distinct floating point numbers. + Note that +0 and -0 are distinct floating point numbers, as are +inf + and -inf. References ---------- - .. [1] Wikipedia, "atan2", - http://en.wikipedia.org/wiki/Atan2 - .. [2] ISO/IEC standard 9899:1999, "Programming language C", 1999. + .. [1] ISO/IEC standard 9899:1999, "Programming language C." Examples -------- @@ -841,7 +846,8 @@ add_newdoc('numpy.core.umath', 'degrees', Returns ------- y : ndarray of floats - The corresponding degree values. + The corresponding degree values; if `out` was supplied this is a + reference to it. See Also -------- @@ -1291,17 +1297,20 @@ add_newdoc('numpy.core.umath', 'fmod', add_newdoc('numpy.core.umath', 'greater', """ - Return (x1 > x2) element-wise. + Return the truth value of (x1 > x2) element-wise. Parameters ---------- x1, x2 : array_like - Input arrays. + Input arrays. If ``x1.shape != x2.shape``, they must be + broadcastable to a common shape (which may be the shape of one or + the other). Returns ------- - Out : {ndarray, bool} - Output array of bools, or a single bool if `x1` and `x2` are scalars. + out : bool or ndarray of bool + Array of bools, or a single bool if `x1` and `x2` are scalars. + See Also -------- @@ -1323,17 +1332,19 @@ add_newdoc('numpy.core.umath', 'greater', add_newdoc('numpy.core.umath', 'greater_equal', """ - Return (x1 >= x2) element-wise. + Return the truth value of (x1 >= x2) element-wise. Parameters ---------- x1, x2 : array_like - Input arrays. + Input arrays. If ``x1.shape != x2.shape``, they must be + broadcastable to a common shape (which may be the shape of one or + the other). Returns ------- - out : {ndarray, bool} - Output array of bools, or a single bool if x1 and x2 are scalars. + out : bool or ndarray of bool + Array of bools, or a single bool if `x1` and `x2` are scalars. See Also -------- @@ -1532,30 +1543,33 @@ add_newdoc('numpy.core.umath', 'isfinite', add_newdoc('numpy.core.umath', 'isinf', """ - Test element-wise for positive or negative infinity, return result as bool - array. + 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. Parameters ---------- x : array_like Input values - y : array_like, optional + out : array_like, optional An array with the same shape as `x` to store the result. Returns ------- - y : {ndarray, bool} + 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. 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 positive or negative infinity; otherwise the - values are False. If a second argument is 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. The return value `y` is then a reference to that array. + 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 -------- @@ -1566,8 +1580,9 @@ add_newdoc('numpy.core.umath', 'isinf', Numpy uses the IEEE Standard for Binary Floating-Point for Arithmetic (IEEE 754). - Errors result if second argument is also supplied with scalar input or - if first and second arguments have different shapes. + Errors result if the second argument is supplied when the first + argument is a scalar, or if the first and second arguments have + different shapes. Examples -------- @@ -1670,21 +1685,23 @@ add_newdoc('numpy.core.umath', 'left_shift', add_newdoc('numpy.core.umath', 'less', """ - Return (x1 < x2) element-wise. + Return the truth value of (x1 < x2) element-wise. Parameters ---------- x1, x2 : array_like - Input arrays. + Input arrays. If ``x1.shape != x2.shape``, they must be + broadcastable to a common shape (which may be the shape of one or + the other). Returns ------- - Out : ndarray of bools - Output array of bools, or a single bool if `x1` and `x2` are scalars. + out : bool or ndarray of bool + Array of bools, or a single bool if `x1` and `x2` are scalars. See Also -------- - less_equal, greater, greater_equal, equal, not_equal + greater, less_equal, greater_equal, equal, not_equal Examples -------- @@ -1695,26 +1712,28 @@ add_newdoc('numpy.core.umath', 'less', add_newdoc('numpy.core.umath', 'less_equal', """ - Return (x1 <= x2) element-wise. + Return the truth value of (x1 =< x2) element-wise. Parameters ---------- x1, x2 : array_like - Input arrays. + Input arrays. If ``x1.shape != x2.shape``, they must be + broadcastable to a common shape (which may be the shape of one or + the other). Returns ------- - Out : {ndarray, bool} - Output array of bools, or a single bool if `x1` and `x2` are scalars. + out : bool or ndarray of bool + Array of bools, or a single bool if `x1` and `x2` are scalars. See Also -------- - less, greater_equal, greater, equal, not_equal + greater, less, greater_equal, equal, not_equal Examples -------- - >>> np.less_equal([1, 2, 3], [2, 2, 2]) - array([ True, True, False], dtype=bool) + >>> np.less_equal([4, 2, 1], [2, 2, 2]) + array([False, True, True], dtype=bool) """) @@ -2041,7 +2060,7 @@ add_newdoc('numpy.core.umath', 'logical_not', Returns ------- - y : {ndarray, bool} + y : bool or ndarray of bool Boolean result with the same shape as `x` of the NOT operation on elements of `x`. @@ -2098,24 +2117,24 @@ add_newdoc('numpy.core.umath', 'logical_or', add_newdoc('numpy.core.umath', 'logical_xor', """ - Compute the truth value of x1 XOR x2 elementwise. + Compute the truth value of x1 XOR x2, element-wise. Parameters ---------- x1, x2 : array_like - Logical XOR is applied to the elements of `x1` and `x2`. - They have to be of the same shape. + Logical XOR is applied to the elements of `x1` and `x2`. They must + be broadcastable to the same shape. Returns ------- - y : {ndarray, bool} - Boolean result with the same shape as `x1` and `x2` of the logical - XOR operation on elements of `x1` and `x2`. + y : bool or ndarray of bool + Boolean result of the logical XOR operation applied to the elements + of `x1` and `x2`; the shape is determined by whether or not + broadcasting of one or both arrays was required. See Also -------- - logical_and, logical_or, logical_not - bitwise_xor + logical_and, logical_or, logical_not, bitwise_xor Examples -------- @@ -2128,6 +2147,12 @@ add_newdoc('numpy.core.umath', 'logical_xor', >>> np.logical_xor(x < 1, x > 3) array([ True, False, False, False, True], dtype=bool) + Simple example showing support of broadcasting + + >>> np.logical_xor(0, np.eye(2)) + array([[ True, False], + [False, True]], dtype=bool) + """) add_newdoc('numpy.core.umath', 'maximum', @@ -2417,13 +2442,13 @@ add_newdoc('numpy.core.umath', 'negative', Parameters ---------- - x : {array_like, scalar} + x : array_like or scalar Input array. Returns ------- - y : {ndarray, scalar} - Returned array or scalar `y=-x`. + y : ndarray or scalar + Returned array or scalar: `y = -x`. Examples -------- @@ -2471,11 +2496,11 @@ add_newdoc('numpy.core.umath', 'ones_like', Equivalent to ``a.copy().fill(1)``. - Please refer to the documentation for `zeros_like`. + Please refer to the documentation for `zeros_like` for further details. See Also -------- - zeros_like + zeros_like, ones Examples -------- @@ -2488,10 +2513,10 @@ add_newdoc('numpy.core.umath', 'ones_like', add_newdoc('numpy.core.umath', 'power', """ - Returns element-wise base array raised to power from second array. + First array elements raised to powers from second array, element-wise. - Raise each base in `x1` to the power of the exponents in `x2`. This - requires that `x1` and `x2` must be broadcastable to the same shape. + Raise each base in `x1` to the positionally-corresponding power in + `x2`. `x1` and `x2` must be broadcastable to the same shape. Parameters ---------- @@ -2542,7 +2567,7 @@ add_newdoc('numpy.core.umath', 'radians', x : array_like Input array in degrees. out : ndarray, optional - Output array of same shape as x. + Output array of same shape as `x`. Returns ------- @@ -2776,12 +2801,13 @@ add_newdoc('numpy.core.umath', 'signbit', 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. + and it must be of the right shape to hold the output. + See `doc.ufuncs`. Returns ------- - out : array_like, bool - Output array. + result : ndarray of bool + Output array, or reference to `out` if that was supplied. Examples -------- @@ -3011,24 +3037,32 @@ add_newdoc('numpy.core.umath', 'sqrt', Parameters ---------- x : array_like - The square root of each element in this array is calculated. + The values whose square-roots are required. + out : ndarray, optional + Alternate array object in which to put the result; if provided, it + must have the same shape as `x` Returns ------- y : ndarray - An array of the same shape as `x`, containing the square-root of - each element in `x`. If any element in `x` - is complex, a complex array is returned. If all of the elements - of `x` are real, negative elements return numpy.nan elements. + An array of the same shape as `x`, containing the positive + square-root of each element in `x`. If any element in `x` is + complex, a complex array is returned (and the square-roots of + negative reals are calculated). If all of the elements in `x` + are real, so is `y`, with negative elements returning ``nan``. + If `out` was provided, `y` is a reference to it. See Also -------- - numpy.lib.scimath.sqrt + lib.scimath.sqrt A version which returns complex numbers when given negative reals. Notes ----- - `sqrt` has a branch cut ``[-inf, 0)`` and is continuous from above on it. + *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.) Examples -------- |