From 88a960594f24bc72266607d65967a0bedac17be2 Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Wed, 2 Apr 2025 12:22:46 +0200 Subject: [PATCH 01/32] Add blank lines prior Default value and description of `include_initial` --- dpnp/dpnp_iface_mathematical.py | 18 ++--- dpnp/dpnp_iface_trigonometric.py | 113 ++++++++++++++++++++++++++++++- 2 files changed, 120 insertions(+), 11 deletions(-) diff --git a/dpnp/dpnp_iface_mathematical.py b/dpnp/dpnp_iface_mathematical.py index 9f9d5dcca082..c6c4a5effe5c 100644 --- a/dpnp/dpnp_iface_mathematical.py +++ b/dpnp/dpnp_iface_mathematical.py @@ -1251,10 +1251,11 @@ def cumulative_prod( be cast if necessary. Default: ``None``. - include_initial : bool, optional - Boolean indicating whether to include the initial value (ones) as - the first value in the output. With ``include_initial=True`` - the shape of the output is different than the shape of the input. + include_initial : {None, bool}, optional + A boolean indicating whether to include the initial value (one) as + the first value along the provided axis in the output. With + ``include_initial=True`` the shape of the output is different than + the shape of the input. Default: ``False``. @@ -1340,10 +1341,11 @@ def cumulative_sum( be cast if necessary. Default: ``None``. - include_initial : bool, optional - Boolean indicating whether to include the initial value (ones) as - the first value in the output. With ``include_initial=True`` - the shape of the output is different than the shape of the input. + include_initial : {None, bool}, optional + A boolean indicating whether to include the initial value (zero) as + the first value along the provided axis in the output. With + ``include_initial=True`` the shape of the output is different than + the shape of the input. Default: ``False``. diff --git a/dpnp/dpnp_iface_trigonometric.py b/dpnp/dpnp_iface_trigonometric.py index 6a4e2398f3f9..cef5ab89eab2 100644 --- a/dpnp/dpnp_iface_trigonometric.py +++ b/dpnp/dpnp_iface_trigonometric.py @@ -123,9 +123,11 @@ def _get_accumulation_res_dt(a, dtype): out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. + Default: ``None``. order : {None, "C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. + Default: ``"K"``. Returns @@ -170,6 +172,7 @@ def _get_accumulation_res_dt(a, dtype): >>> x = np.array([1, -1]) >>> np.arccos(x) array([0.0, 3.14159265]) + """ arccos = DPNPUnaryFunc( @@ -199,9 +202,11 @@ def _get_accumulation_res_dt(a, dtype): out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. + Default: ``None``. order : {None, "C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. + Default: ``"K"``. Returns @@ -247,6 +252,7 @@ def _get_accumulation_res_dt(a, dtype): >>> x = np.array([1.0, np.e, 10.0]) >>> np.arccosh(x) array([0.0, 1.65745445, 2.99322285]) + """ arccosh = DPNPUnaryFunc( @@ -276,9 +282,11 @@ def _get_accumulation_res_dt(a, dtype): out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. + Default: ``None``. order : {None, "C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. + Default: ``"K"``. Returns @@ -326,6 +334,7 @@ def _get_accumulation_res_dt(a, dtype): >>> x = np.array([0, 1, -1]) >>> np.arcsin(x) array([0.0, 1.5707963267948966, -1.5707963267948966]) + """ arcsin = DPNPUnaryFunc( @@ -355,9 +364,11 @@ def _get_accumulation_res_dt(a, dtype): out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. + Default: ``None``. order : {None, "C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. + Default: ``"K"``. Returns @@ -403,6 +414,7 @@ def _get_accumulation_res_dt(a, dtype): >>> x = np.array([np.e, 10.0]) >>> np.arcsinh(x) array([1.72538256, 2.99822295]) + """ arcsinh = DPNPUnaryFunc( @@ -432,9 +444,11 @@ def _get_accumulation_res_dt(a, dtype): out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. + Default: ``None``. order : {None, "C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. + Default: ``"K"``. Returns @@ -481,6 +495,7 @@ def _get_accumulation_res_dt(a, dtype): >>> x = np.array([0, 1]) >>> np.arctan(x) array([0.0, 0.78539816]) + """ arctan = DPNPUnaryFunc( @@ -521,9 +536,11 @@ def _get_accumulation_res_dt(a, dtype): out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. + Default: ``None``. order : {None, "C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. + Default: ``"K"``. Returns @@ -565,6 +582,7 @@ def _get_accumulation_res_dt(a, dtype): >>> x2 = np.array([-1, -1, +1, +1]) >>> np.arctan2(x1, x2) * 180 / np.pi array([-135., -45., 45., 135.]) + """ arctan2 = DPNPBinaryFunc( @@ -594,9 +612,11 @@ def _get_accumulation_res_dt(a, dtype): out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. + Default: ``None``. order : {None, "C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. + Default: ``"K"``. Returns @@ -641,6 +661,7 @@ def _get_accumulation_res_dt(a, dtype): >>> x = np.array([0, -0.5]) >>> np.arctanh(x) array([0.0, -0.54930614]) + """ arctanh = DPNPUnaryFunc( @@ -667,9 +688,11 @@ def _get_accumulation_res_dt(a, dtype): out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. + Default: ``None``. order : {None, "C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. + Default: ``"K"``. Returns @@ -695,6 +718,7 @@ def _get_accumulation_res_dt(a, dtype): >>> x = np.array([1, 8, 27]) >>> np.cbrt(x) array([1., 2., 3.]) + """ cbrt = DPNPUnaryFunc( @@ -719,9 +743,11 @@ def _get_accumulation_res_dt(a, dtype): out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. + Default: ``None``. order : {None, "C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. + Default: ``"K"``. Returns @@ -749,6 +775,7 @@ def _get_accumulation_res_dt(a, dtype): >>> x = np.array([0, np.pi/2, np.pi]) >>> np.cos(x) array([ 1.000000e+00, -4.371139e-08, -1.000000e+00]) + """ cos = DPNPUnaryFunc( @@ -773,9 +800,11 @@ def _get_accumulation_res_dt(a, dtype): out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. + Default: ``None``. order : {None, "C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. + Default: ``"K"``. Returns @@ -804,6 +833,7 @@ def _get_accumulation_res_dt(a, dtype): >>> x = np.array([0, np.pi/2, np.pi]) >>> np.cosh(x) array([1.0, 2.5091786, 11.591953]) + """ cosh = DPNPUnaryFunc( @@ -831,6 +861,7 @@ def cumlogsumexp( Axis or axes along which values must be computed. If a tuple of unique integers, values are computed over multiple axes. If ``None``, the result is computed over the entire array. + Default: ``None``. dtype : {None, str, dtype object}, optional Data type of the returned array. If ``None``, the default data type is @@ -847,16 +878,20 @@ def cumlogsumexp( If the data type (either specified or resolved) differs from the data type of `x`, the input array elements are cast to the specified data type before computing the result. + Default: ``None``. include_initial : {None, bool}, optional - A boolean indicating whether to include the initial value (i.e., the - additive identity, zero) as the first value along the provided axis in - the output. + A boolean indicating whether to include the initial value (negative + infinity) as the first value along the provided axis in the output. + With ``include_initial=True`` the shape of the output is different than + the shape of the input. + Default: ``False``. out : {None, dpnp.ndarray, usm_ndarray}, optional The array into which the result is written. The data type of `out` must match the expected shape and the expected data type of the result or (if provided) `dtype`. If ``None`` then a new array is returned. + Default: ``None``. Returns @@ -915,9 +950,11 @@ def cumlogsumexp( out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. + Default: ``None``. order : {None, "C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. + Default: ``"K"``. Returns @@ -948,6 +985,7 @@ def cumlogsumexp( >>> x = np.array(180) >>> np.deg2rad(x) array(3.14159265) + """ deg2rad = DPNPUnaryFunc( @@ -970,9 +1008,11 @@ def cumlogsumexp( out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. + Default: ``None``. order : {None, "C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. + Default: ``"K"``. Returns @@ -1006,6 +1046,7 @@ def cumlogsumexp( >>> r = np.degrees(rad, out) >>> np.all(r == out) array(True) + """ degrees = DPNPUnaryFunc( @@ -1028,9 +1069,11 @@ def cumlogsumexp( out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. + Default: ``None``. order : {None, "C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. + Default: ``"K"``. Returns @@ -1057,6 +1100,7 @@ def cumlogsumexp( >>> x = np.arange(3.) >>> np.exp(x) array([1.0, 2.718281828, 7.389056099]) + """ exp = DPNPUnaryFunc( @@ -1081,9 +1125,11 @@ def cumlogsumexp( out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. + Default: ``None``. order : {None, "C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. + Default: ``"K"``. Returns @@ -1111,6 +1157,7 @@ def cumlogsumexp( >>> x = np.arange(3.) >>> np.exp2(x) array([1., 2., 4.]) + """ exp2 = DPNPUnaryFunc( @@ -1137,9 +1184,11 @@ def cumlogsumexp( out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. + Default: ``None``. order : {None, "C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. + Default: ``"K"``. Returns @@ -1173,6 +1222,7 @@ def cumlogsumexp( >>> np.exp(np.array(1e-10)) - 1 array(1.000000082740371e-10) + """ expm1 = DPNPUnaryFunc( @@ -1204,9 +1254,11 @@ def cumlogsumexp( out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. + Default: ``None``. order : {None, "C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. + Default: ``"K"``. Returns @@ -1241,6 +1293,7 @@ def cumlogsumexp( array([[ 5., 5., 5.], [ 5., 5., 5.], [ 5., 5., 5.]]) + """ hypot = DPNPBinaryFunc( @@ -1265,9 +1318,11 @@ def cumlogsumexp( out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. + Default: ``None``. order : {None, "C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. + Default: ``"K"``. Returns @@ -1296,6 +1351,7 @@ def cumlogsumexp( >>> x = np.array([1, np.e, np.e**2, 0]) >>> np.log(x) array([ 0., 1., 2., -inf]) + """ log = DPNPUnaryFunc( @@ -1320,9 +1376,11 @@ def cumlogsumexp( out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. + Default: ``None``. order : {None, "C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. + Default: ``"K"``. Returns @@ -1353,6 +1411,7 @@ def cumlogsumexp( >>> np.log10(np.array([1e-15, -3.])) array([-15., nan]) + """ log10 = DPNPUnaryFunc( @@ -1380,9 +1439,11 @@ def cumlogsumexp( out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. + Default: ``None``. order : {None, "C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. + Default: ``"K"``. Returns @@ -1416,6 +1477,7 @@ def cumlogsumexp( >>> np.log(array(1 + 1e-99)) array(0.0) + """ log1p = DPNPUnaryFunc( @@ -1440,9 +1502,11 @@ def cumlogsumexp( out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. + Default: ``None``. order : {None, "C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. + Default: ``"K"``. Returns @@ -1474,6 +1538,7 @@ def cumlogsumexp( >>> xi = np.array([0+1.j, 1, 2+0.j, 4.j]) >>> np.log2(xi) array([ 0.+2.26618007j, 0.+0.j , 1.+0.j , 2.+2.26618007j]) + """ log2 = DPNPUnaryFunc( @@ -1511,9 +1576,11 @@ def cumlogsumexp( out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. + Default: ``None``. order : {None, "C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. + Default: ``"K"``. Returns @@ -1547,6 +1614,7 @@ def cumlogsumexp( array(-113.87649168) >>> np.exp(prob12) array(3.5e-50) + """ logaddexp = DPNPBinaryFunc( @@ -1585,9 +1653,11 @@ def cumlogsumexp( out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. + Default: ``None``. order : {None, "C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. + Default: ``"K"``. Returns @@ -1618,6 +1688,7 @@ def cumlogsumexp( (array(-166.09640474), array(-164.77447665), array(-164.28904982)) >>> 2**prob12 array(3.5e-50) + """ logaddexp2 = DPNPBinaryFunc( @@ -1641,6 +1712,7 @@ def logsumexp(x, /, *, axis=None, dtype=None, keepdims=False, out=None): Axis or axes along which values must be computed. If a tuple of unique integers, values are computed over multiple axes. If ``None``, the result is computed over the entire array. + Default: ``None``. dtype : {None, str, dtype object}, optional Data type of the returned array. If ``None``, the default data type is @@ -1657,6 +1729,7 @@ def logsumexp(x, /, *, axis=None, dtype=None, keepdims=False, out=None): If the data type (either specified or resolved) differs from the data type of `x`, the input array elements are cast to the specified data type before computing the result. + Default: ``None``. keepdims : {None, bool}, optional If ``True``, the reduced axes (dimensions) are included in the result @@ -1668,6 +1741,7 @@ def logsumexp(x, /, *, axis=None, dtype=None, keepdims=False, out=None): The array into which the result is written. The data type of `out` must match the expected shape and the expected data type of the result or (if provided) `dtype`. If ``None`` then a new array is returned. + Default: ``None``. Returns @@ -1726,9 +1800,11 @@ def logsumexp(x, /, *, axis=None, dtype=None, keepdims=False, out=None): out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. + Default: ``None``. order : {None, "C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. + Default: ``"K"``. Returns @@ -1759,6 +1835,7 @@ def logsumexp(x, /, *, axis=None, dtype=None, keepdims=False, out=None): >>> x = np.array(np.pi / 2) >>> np.rad2deg(x) array(90.) + """ rad2deg = DPNPUnaryFunc( @@ -1781,9 +1858,11 @@ def logsumexp(x, /, *, axis=None, dtype=None, keepdims=False, out=None): out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. + Default: ``None``. order : {None, "C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. + Default: ``"K"``. Returns @@ -1818,6 +1897,7 @@ def logsumexp(x, /, *, axis=None, dtype=None, keepdims=False, out=None): >>> ret = np.radians(deg, out) >>> ret is out True + """ radians = DPNPUnaryFunc( @@ -1840,9 +1920,11 @@ def logsumexp(x, /, *, axis=None, dtype=None, keepdims=False, out=None): out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. + Default: ``None``. order : {None, "C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. + Default: ``"K"``. Returns @@ -1868,6 +1950,7 @@ def logsumexp(x, /, *, axis=None, dtype=None, keepdims=False, out=None): >>> x = np.array([1, 2., 3.33]) >>> np.reciprocal(x) array([1.0, 0.5, 0.3003003]) + """ reciprocal = DPNPUnaryFunc( @@ -1891,6 +1974,7 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): Axis or axes along which values must be computed. If a tuple of unique integers, values are computed over multiple axes. If ``None``, the result is computed over the entire array. + Default: ``None``. dtype : {None, str, dtype object}, optional Data type of the returned array. If ``None``, the default data type is @@ -1907,6 +1991,7 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): If the data type (either specified or resolved) differs from the data type of `x`, the input array elements are cast to the specified data type before computing the result. + Default: ``None``. keepdims : {None, bool}, optional If ``True``, the reduced axes (dimensions) are included in the result @@ -1918,6 +2003,7 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): The array into which the result is written. The data type of `out` must match the expected shape and the expected data type of the result or (if provided) `dtype`. If ``None`` then a new array is returned. + Default: ``None``. Returns @@ -1970,6 +2056,7 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): out : {None, dpnp.ndarray, usm_ndarray}, optional: Output array to populate. Array must have the correct shape and the expected data type. + Default: ``None``. order : {None, "C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is `None`. @@ -1999,6 +2086,7 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): >>> x = np.array([1, 8, 27]) >>> np.rsqrt(x) array([1. , 0.35355338, 0.19245009]) + """ rsqrt = DPNPUnaryFunc( @@ -2021,9 +2109,11 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. + Default: ``None``. order : {None, "C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. + Default: ``"K"``. Returns @@ -2051,6 +2141,7 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): >>> x = np.array([0, np.pi/2, np.pi]) >>> np.sin(x) array([ 0.000000e+00, 1.000000e+00, -8.742278e-08]) + """ sin = DPNPUnaryFunc( @@ -2075,9 +2166,11 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. + Default: ``None``. order : {None, "C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. + Default: ``"K"``. Returns @@ -2104,6 +2197,7 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): >>> x = np.array([0, np.pi/2, np.pi]) >>> np.sinh(x) array([0.0, 2.3012989, 11.548739]) + """ sinh = DPNPUnaryFunc( @@ -2128,9 +2222,11 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. + Default: ``None``. order : {None, "C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. + Default: ``"K"``. Returns @@ -2160,6 +2256,7 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): >>> x2 = np.array([4, -1, np.inf]) >>> np.sqrt(x2) array([ 2., nan, inf]) + """ sqrt = DPNPUnaryFunc( @@ -2184,9 +2281,11 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. + Default: ``None``. order : {None, "C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. + Default: ``"K"``. Returns @@ -2215,6 +2314,7 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): >>> x = np.array([-1j, 1]) >>> np.square(x) array([-1.+0.j, 1.+0.j]) + """ square = DPNPUnaryFunc( @@ -2239,9 +2339,11 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. + Default: ``None``. order : {None, "C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. + Default: ``"K"``. Returns @@ -2269,6 +2371,7 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): >>> x = np.array([-np.pi, np.pi/2, np.pi]) >>> np.tan(x) array([1.22460635e-16, 1.63317787e+16, -1.22460635e-16]) + """ tan = DPNPUnaryFunc( @@ -2293,9 +2396,11 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. + Default: ``None``. order : {None, "C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. + Default: ``"K"``. Returns @@ -2323,6 +2428,7 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): >>> x = np.array([0, -np.pi, np.pi/2, np.pi]) >>> np.tanh(x) array([0.0, -0.996272, 0.917152, 0.996272]) + """ tanh = DPNPUnaryFunc( @@ -2359,6 +2465,7 @@ def unwrap(p, discont=None, axis=-1, *, period=2 * dpnp.pi): alias for ``period / 2``. Values below ``period / 2`` are treated as if they were ``period / 2``. To have an effect different from the default, `discont` should be larger than ``period / 2``. + Default: ``None``. axis : int, optional Axis along which unwrap will operate, default is the last axis. From bdf559928d6a8657cc5da9edfcd851aa5afa903c Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Wed, 2 Apr 2025 13:37:29 +0200 Subject: [PATCH 02/32] Update docstring of `acos` function to use `math` where applicable. Also `arccos` is now alias on `acos` function. Limitation block is aligned along all trigonometric functions. --- dpnp/dpnp_iface_trigonometric.py | 56 ++++++++++++++++++-------------- 1 file changed, 31 insertions(+), 25 deletions(-) diff --git a/dpnp/dpnp_iface_trigonometric.py b/dpnp/dpnp_iface_trigonometric.py index cef5ab89eab2..2c7bc6b97938 100644 --- a/dpnp/dpnp_iface_trigonometric.py +++ b/dpnp/dpnp_iface_trigonometric.py @@ -109,17 +109,18 @@ def _get_accumulation_res_dt(a, dtype): _ACOS_DOCSTRING = r""" -Computes inverse cosine for each element `x_i` for input array `x`. +Computes inverse cosine for each element :math:`x_i` for input array `x`. -The inverse of :obj:`dpnp.cos` so that, if ``y = cos(x)``, then ``x = arccos(y)``. -Note that :obj:`dpnp.acos` is an alias of :obj:`dpnp.arccos`. +The inverse of :obj:`dpnp.cos` so that, if :math:`y = cos(x)`, then +:math:`x = acos(y)`. Note that :obj:`dpnp.arccos` is an alias of +:obj:`dpnp.acos`. -For full documentation refer to :obj:`numpy.arccos`. +For full documentation refer to :obj:`numpy.acos`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + Input array, expected to have a floating-point data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -133,9 +134,9 @@ def _get_accumulation_res_dt(a, dtype): Returns ------- out : dpnp.ndarray - An array containing the element-wise inverse cosine, in radians - and in the closed interval `[-pi/2, pi/2]`. The data type - of the returned array is determined by the Type Promotion Rules. + An array containing the element-wise inverse cosine, in radians and in the + closed interval :math:`[0, pi]`. The data type of the returned array is + determined by the Type Promotion Rules. Limitations ----------- @@ -152,31 +153,32 @@ def _get_accumulation_res_dt(a, dtype): Notes ----- -:obj:`dpnp.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]`. +:obj:`dpnp.acos` is a multivalued function: for each `x` there are infinitely +many numbers `z` such that :math:`cos(z) = x`. The convention is to return the +angle `z` whose real part lies in :math:`[0, pi]`. -For real-valued input data types, :obj:`dpnp.arccos` always returns real output. -For each value that cannot be expressed as a real number or infinity, it yields -``nan``. +For real-valued floating-point input data types, :obj:`dpnp.acos` always +returns real output. For each value that cannot be expressed as a real number +or infinity, it yields ``NaN``. -For complex-valued input, :obj:`dpnp.arccos` 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. +For complex floating-point input data types, :obj:`dpnp.acos` is a complex +analytic function that has, by convention, the branch cuts :math:`[-inf, -1]` +and :math:`[1, inf]` and is continuous from above on the former and from below +on the latter. -The inverse cos is also known as :math:`acos` or :math:`cos^{-1}`. +The inverse cosine is also known as :math:`arccos` or :math:`cos^{-1}`. Examples -------- >>> import dpnp as np >>> x = np.array([1, -1]) ->>> np.arccos(x) +>>> np.acos(x) array([0.0, 3.14159265]) """ -arccos = DPNPUnaryFunc( - "arccos", +acos = DPNPUnaryFunc( + "acos", ti._acos_result_type, ti._acos, _ACOS_DOCSTRING, @@ -184,7 +186,7 @@ def _get_accumulation_res_dt(a, dtype): mkl_impl_fn="_acos", ) -acos = arccos # acos is an alias for arccos +arccos = acos # arccos is an alias for acos _ACOSH_DOCSTRING = r""" @@ -553,7 +555,7 @@ def _get_accumulation_res_dt(a, dtype): Limitations ----------- Parameters `where` and `subok` are supported with their default values. -Keyword arguments `kwargs` are currently unsupported. +Keyword argument `kwargs` is currently unsupported. Otherwise ``NotImplementedError`` exception will be raised. See Also @@ -1335,6 +1337,7 @@ def cumlogsumexp( Limitations ----------- Parameters `where` and `subok` are supported with their default values. +Keyword argument `kwargs` is currently unsupported. Otherwise ``NotImplementedError`` exception will be raised. See Also @@ -1592,7 +1595,7 @@ def cumlogsumexp( Limitations ----------- Parameters `where` and `subok` are supported with their default values. -Keyword arguments `kwargs` are currently unsupported. +Keyword argument `kwargs` is currently unsupported. Otherwise ``NotImplementedError`` exception will be raised. See Also @@ -1669,7 +1672,7 @@ def cumlogsumexp( Limitations ----------- Parameters `where` and `subok` are supported with their default values. -Keyword arguments `kwargs` are currently unsupported. +Keyword argument `kwargs` is currently unsupported. Otherwise ``NotImplementedError`` exception will be raised. See Also @@ -2181,6 +2184,7 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): Limitations ----------- +Parameters `where` and `subok` are supported with their default values. Keyword argument `kwargs` is currently unsupported. Otherwise ``NotImplementedError`` exception will be raised. @@ -2239,6 +2243,7 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): Limitations ----------- Parameters `where` and `subok` are supported with their default values. +Keyword argument `kwargs` is currently unsupported. Otherwise ``NotImplementedError`` exception will be raised. See Also @@ -2297,6 +2302,7 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): Limitations ----------- Parameters `where` and `subok` are supported with their default values. +Keyword argument `kwargs` is currently unsupported. Otherwise ``NotImplementedError`` exception will be raised. See Also From 790e50c18278440671b00d0f8c67197cbafcd7ad Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Wed, 2 Apr 2025 13:46:28 +0200 Subject: [PATCH 03/32] Replace nan with NaN --- dpnp/dpnp_iface_mathematical.py | 2 +- dpnp/dpnp_iface_trigonometric.py | 10 +++++----- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/dpnp/dpnp_iface_mathematical.py b/dpnp/dpnp_iface_mathematical.py index c6c4a5effe5c..dc2dd9c41da7 100644 --- a/dpnp/dpnp_iface_mathematical.py +++ b/dpnp/dpnp_iface_mathematical.py @@ -3495,7 +3495,7 @@ def nan_to_num(x, copy=True, nan=0.0, posinf=None, neginf=None): >>> a ** b array([ 0, 1, 8, 27, 16, 5]) -Negative values raised to a non-integral value will result in ``nan``. +Negative values raised to a non-integral value will result in ``NaN``. >>> d = dp.array([-1.0, -4.0]) >>> dp.power(d, 1.5) diff --git a/dpnp/dpnp_iface_trigonometric.py b/dpnp/dpnp_iface_trigonometric.py index 2c7bc6b97938..e12668cc5cf4 100644 --- a/dpnp/dpnp_iface_trigonometric.py +++ b/dpnp/dpnp_iface_trigonometric.py @@ -241,7 +241,7 @@ def _get_accumulation_res_dt(a, dtype): For real-valued input data types, :obj:`dpnp.arccosh` always returns real output. For each value that cannot be expressed as a real number or infinity, it yields -``nan``. +``NaN``. For complex-valued input, :obj:`dpnp.arccosh` is a complex analytic function that has, by convention, the branch cuts `[-inf, 1]` and is continuous from above. @@ -322,7 +322,7 @@ def _get_accumulation_res_dt(a, dtype): For real-valued input data types, :obj:`dpnp.arcsin` always returns real output. For each value that cannot be expressed as a real number or infinity, it yields -``nan``. +``NaN``. For complex-valued input, :obj:`dpnp.arcsin` is a complex analytic function that has, by convention, the branch cuts `[-inf, -1]` and `[1, inf]` and is continuous @@ -401,7 +401,7 @@ def _get_accumulation_res_dt(a, dtype): For real-valued input data types, :obj:`dpnp.arcsinh` always returns real output. For each value that cannot be expressed as a real number or infinity, it yields -``nan``. +``NaN``. For complex-valued input, :obj:`dpnp.arcsinh` is a complex analytic function that has, by convention, the branch cuts `[1j, infj]` and `[`1j, -infj]` and is continuous @@ -483,7 +483,7 @@ def _get_accumulation_res_dt(a, dtype): For real-valued input data types, :obj:`dpnp.arctan` always returns real output. For each value that cannot be expressed as a real number or infinity, it yields -``nan``. +``NaN``. For complex-valued input, :obj:`dpnp.arctan` is a complex analytic function that has, by convention, the branch cuts `[1j, infj]` and `[-1j, -infj]` and is continuous @@ -649,7 +649,7 @@ def _get_accumulation_res_dt(a, dtype): For real-valued input data types, :obj:`dpnp.arctanh` always returns real output. For each value that cannot be expressed as a real number or infinity, it yields -``nan``. +``NaN``. For complex-valued input, :obj:`dpnp.arctanh` is a complex analytic function that has, by convention, the branch cuts `[-1, -inf]` and `[1, inf]` and is is continuous From 215725825ed2a214bd756d0fce92fd8e228fdbca Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Wed, 2 Apr 2025 14:10:37 +0200 Subject: [PATCH 04/32] Use :math:`\pi` where applicable --- dpnp/dpnp_iface_trigonometric.py | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/dpnp/dpnp_iface_trigonometric.py b/dpnp/dpnp_iface_trigonometric.py index e12668cc5cf4..71b462043af4 100644 --- a/dpnp/dpnp_iface_trigonometric.py +++ b/dpnp/dpnp_iface_trigonometric.py @@ -135,7 +135,7 @@ def _get_accumulation_res_dt(a, dtype): ------- out : dpnp.ndarray An array containing the element-wise inverse cosine, in radians and in the - closed interval :math:`[0, pi]`. The data type of the returned array is + closed interval :math:`[0, \pi]`. The data type of the returned array is determined by the Type Promotion Rules. Limitations @@ -155,7 +155,7 @@ def _get_accumulation_res_dt(a, dtype): ----- :obj:`dpnp.acos` is a multivalued function: for each `x` there are infinitely many numbers `z` such that :math:`cos(z) = x`. The convention is to return the -angle `z` whose real part lies in :math:`[0, pi]`. +angle `z` whose real part lies in :math:`[0, \pi]`. For real-valued floating-point input data types, :obj:`dpnp.acos` always returns real output. For each value that cannot be expressed as a real number @@ -295,7 +295,7 @@ def _get_accumulation_res_dt(a, dtype): ------- out : dpnp.ndarray An array containing the element-wise inverse sine, in radians - and in the closed interval `[-pi/2, pi/2]`. The data type + and in the closed interval `[-\pi/2, \pi/2]`. The data type of the returned array is determined by the Type Promotion Rules. Limitations @@ -318,7 +318,7 @@ def _get_accumulation_res_dt(a, dtype): ----- :obj:`dpnp.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]`. +angle `z` whose real part lies in `[-\pi/2, \pi/2]`. For real-valued input data types, :obj:`dpnp.arcsin` always returns real output. For each value that cannot be expressed as a real number or infinity, it yields @@ -397,7 +397,7 @@ def _get_accumulation_res_dt(a, dtype): ----- :obj:`dpnp.arcsinh` 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]`. +angle `z` whose real part lies in `[-\pi/2, \pi/2]`. For real-valued input data types, :obj:`dpnp.arcsinh` always returns real output. For each value that cannot be expressed as a real number or infinity, it yields @@ -457,7 +457,7 @@ def _get_accumulation_res_dt(a, dtype): ------- out : dpnp.ndarray An array containing the element-wise inverse tangent, in radians - and in the closed interval `[-pi/2, pi/2]`. The data type + and in the closed interval `[-\pi/2, \pi/2]`. The data type of the returned array is determined by the Type Promotion Rules. Limitations @@ -479,7 +479,7 @@ def _get_accumulation_res_dt(a, dtype): ----- :obj:`dpnp.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]`. +angle `z` whose real part lies in `[-\pi/2, \pi/2]`. For real-valued input data types, :obj:`dpnp.arctan` always returns real output. For each value that cannot be expressed as a real number or infinity, it yields @@ -645,7 +645,7 @@ def _get_accumulation_res_dt(a, dtype): ----- :obj:`dpnp.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 -angle `z` whose real part lies in `[-pi/2, pi/2]`. +angle `z` whose real part lies in `[-\pi/2, \pi/2]`. For real-valued input data types, :obj:`dpnp.arctanh` always returns real output. For each value that cannot be expressed as a real number or infinity, it yields From 1f0f9dd202918d1b27e784e238a9fbb8a30451f6 Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Wed, 2 Apr 2025 14:46:56 +0200 Subject: [PATCH 05/32] Use :math:`\infty` where applicable --- dpnp/dpnp_iface_trigonometric.py | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/dpnp/dpnp_iface_trigonometric.py b/dpnp/dpnp_iface_trigonometric.py index 71b462043af4..0d644275e2d1 100644 --- a/dpnp/dpnp_iface_trigonometric.py +++ b/dpnp/dpnp_iface_trigonometric.py @@ -162,9 +162,9 @@ def _get_accumulation_res_dt(a, dtype): or infinity, it yields ``NaN``. For complex floating-point input data types, :obj:`dpnp.acos` is a complex -analytic function that has, by convention, the branch cuts :math:`[-inf, -1]` -and :math:`[1, inf]` and is continuous from above on the former and from below -on the latter. +analytic function that has, by convention, the branch cuts +:math:`[-\infty, -1]` and :math:`[1, \infty]` and is continuous from above on +the former and from below on the latter. The inverse cosine is also known as :math:`arccos` or :math:`cos^{-1}`. @@ -215,7 +215,7 @@ def _get_accumulation_res_dt(a, dtype): ------- out : dpnp.ndarray An array containing the element-wise inverse hyperbolic cosine, in - radians and in the half-closed interval `[0, inf)`. The data type + radians and in the half-closed interval `[0, \infty)`. The data type of the returned array is determined by the Type Promotion Rules. Limitations @@ -237,14 +237,14 @@ def _get_accumulation_res_dt(a, dtype): ----- :obj:`dpnp.arccosh` is a multivalued function: for each `x` there are infinitely many numbers `z` such that ``cosh(z) = x``. The convention is to return the -angle `z` whose real part lies in `[0, inf]`. +angle `z` whose real part lies in `[0, \infty]`. For real-valued input data types, :obj:`dpnp.arccosh` always returns real output. For each value that cannot be expressed as a real number or infinity, it yields ``NaN``. For complex-valued input, :obj:`dpnp.arccosh` is a complex analytic function that -has, by convention, the branch cuts `[-inf, 1]` and is continuous from above. +has, by convention, the branch cuts `[-\infty, 1]` and is continuous from above. The inverse hyperbolic cos is also known as :math:`acosh` or :math:`cosh^{-1}`. @@ -325,7 +325,7 @@ def _get_accumulation_res_dt(a, dtype): ``NaN``. For complex-valued input, :obj:`dpnp.arcsin` is a complex analytic function that -has, by convention, the branch cuts `[-inf, -1]` and `[1, inf]` and is continuous +has, by convention, the branch cuts `[-\infty, -1]` and `[1, \infty]` and is continuous from above on the former and from below on the latter. The inverse sine is also known as :math:`asin` or :math:`sin^{-1}`. @@ -652,7 +652,7 @@ def _get_accumulation_res_dt(a, dtype): ``NaN``. For complex-valued input, :obj:`dpnp.arctanh` is a complex analytic function that -has, by convention, the branch cuts `[-1, -inf]` and `[1, inf]` and is is continuous +has, by convention, the branch cuts `[-1, -\infty]` and `[1, \infty]` and is is continuous from above on the former and from below on the latter. The inverse hyperbolic tan is also known as :math:`atanh` or :math:`tanh^{-1}`. From 63966846438022c6db8bdced7c2a46c3491f7c33 Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Wed, 2 Apr 2025 15:15:05 +0200 Subject: [PATCH 06/32] Update docstring of `acosh` function to use math where applicable. Also `arccosh` is now alias on `acosh` function. --- dpnp/dpnp_iface_trigonometric.py | 51 ++++++++++++++++++-------------- 1 file changed, 28 insertions(+), 23 deletions(-) diff --git a/dpnp/dpnp_iface_trigonometric.py b/dpnp/dpnp_iface_trigonometric.py index 0d644275e2d1..327984323f1b 100644 --- a/dpnp/dpnp_iface_trigonometric.py +++ b/dpnp/dpnp_iface_trigonometric.py @@ -155,7 +155,7 @@ def _get_accumulation_res_dt(a, dtype): ----- :obj:`dpnp.acos` is a multivalued function: for each `x` there are infinitely many numbers `z` such that :math:`cos(z) = x`. The convention is to return the -angle `z` whose real part lies in :math:`[0, \pi]`. +angle `z` whose the real part lies in the interval :math:`[0, \pi]`. For real-valued floating-point input data types, :obj:`dpnp.acos` always returns real output. For each value that cannot be expressed as a real number @@ -163,7 +163,7 @@ def _get_accumulation_res_dt(a, dtype): For complex floating-point input data types, :obj:`dpnp.acos` is a complex analytic function that has, by convention, the branch cuts -:math:`[-\infty, -1]` and :math:`[1, \infty]` and is continuous from above on +:math:`(-\infty, -1]` and :math:`[1, \infty)` and is continuous from above on the former and from below on the latter. The inverse cosine is also known as :math:`arccos` or :math:`cos^{-1}`. @@ -190,17 +190,19 @@ def _get_accumulation_res_dt(a, dtype): _ACOSH_DOCSTRING = r""" -Computes inverse hyperbolic cosine for each element `x_i` for input array `x`. +Computes inverse hyperbolic cosine for each element :math:`x_i` for input array +`x`. -The inverse of :obj:`dpnp.cosh` so that, if ``y = cosh(x)``, then ``x = arccosh(y)``. -Note that :obj:`dpnp.acosh` is an alias of :obj:`dpnp.arccosh`. +The inverse of :obj:`dpnp.cosh` so that, if :math:`y = cosh(x)`, then +:math:`x = acosh(y)`. Note that :obj:`dpnp.arccosh` is an alias of +:obj:`dpnp.acosh`. -For full documentation refer to :obj:`numpy.arccosh`. +For full documentation refer to :obj:`numpy.acosh`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + Input array, expected to have a floating-point data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -214,9 +216,9 @@ def _get_accumulation_res_dt(a, dtype): Returns ------- out : dpnp.ndarray - An array containing the element-wise inverse hyperbolic cosine, in - radians and in the half-closed interval `[0, \infty)`. The data type - of the returned array is determined by the Type Promotion Rules. + An array containing the element-wise inverse hyperbolic cosine, in radians + and in the half-closed interval :math:`[0, \infty)`. The data type of the + returned array is determined by the Type Promotion Rules. Limitations ----------- @@ -235,30 +237,33 @@ def _get_accumulation_res_dt(a, dtype): Notes ----- -:obj:`dpnp.arccosh` is a multivalued function: for each `x` there are infinitely -many numbers `z` such that ``cosh(z) = x``. The convention is to return the -angle `z` whose real part lies in `[0, \infty]`. +:obj:`dpnp.acosh` is a multivalued function: for each `x` there are infinitely +many numbers `z` such that :math:`cosh(z) = x`. The convention is to return the +angle `z` whose the real part lies in the interval :math:`[0, \infty)` and the +imaginary part in the interval :math:`[-\pi, \pi]`. -For real-valued input data types, :obj:`dpnp.arccosh` always returns real output. -For each value that cannot be expressed as a real number or infinity, it yields -``NaN``. +For real-valued floating-point input data types, :obj:`dpnp.acosh` always +returns real output. For each value that cannot be expressed as a real number +or infinity, it yields ``NaN``. -For complex-valued input, :obj:`dpnp.arccosh` is a complex analytic function that -has, by convention, the branch cuts `[-\infty, 1]` and is continuous from above. +For complex floating-point input data types, :obj:`dpnp.acosh` is a complex +analytic function that has, by convention, the branch cuts :math:`(-\infty, 1]` +and is continuous from above on it. -The inverse hyperbolic cos is also known as :math:`acosh` or :math:`cosh^{-1}`. +The inverse hyperbolic cosine is also known as :math:`arccosh` or +:math:`cosh^{-1}`. Examples -------- >>> import dpnp as np >>> x = np.array([1.0, np.e, 10.0]) ->>> np.arccosh(x) +>>> np.acosh(x) array([0.0, 1.65745445, 2.99322285]) """ -arccosh = DPNPUnaryFunc( - "arccosh", +acosh = DPNPUnaryFunc( + "acosh", ti._acosh_result_type, ti._acosh, _ACOSH_DOCSTRING, @@ -266,7 +271,7 @@ def _get_accumulation_res_dt(a, dtype): mkl_impl_fn="_acosh", ) -acosh = arccosh # acosh is an alias for arccosh +arccosh = acosh # arccosh is an alias for acosh _ASIN_DOCSTRING = r""" From beb9c1efee71baa0c2582b3cc2f1b556de5878ba Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Wed, 2 Apr 2025 15:49:38 +0200 Subject: [PATCH 07/32] Update `See also` in `acos` and `acosh` functions --- dpnp/dpnp_iface_trigonometric.py | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/dpnp/dpnp_iface_trigonometric.py b/dpnp/dpnp_iface_trigonometric.py index 327984323f1b..d1b1c341697b 100644 --- a/dpnp/dpnp_iface_trigonometric.py +++ b/dpnp/dpnp_iface_trigonometric.py @@ -147,9 +147,9 @@ def _get_accumulation_res_dt(a, dtype): See Also -------- :obj:`dpnp.cos` : Trigonometric cosine, element-wise. -:obj:`dpnp.arctan` : Trigonometric inverse tangent, element-wise. -:obj:`dpnp.arcsin` : Trigonometric inverse sine, element-wise. -:obj:`dpnp.arccosh` : Hyperbolic inverse cosine, element-wise. +:obj:`dpnp.atan` : Trigonometric inverse tangent, element-wise. +:obj:`dpnp.asin` : Trigonometric inverse sine, element-wise. +:obj:`dpnp.acosh` : Hyperbolic inverse cosine, element-wise. Notes ----- @@ -166,7 +166,7 @@ def _get_accumulation_res_dt(a, dtype): :math:`(-\infty, -1]` and :math:`[1, \infty)` and is continuous from above on the former and from below on the latter. -The inverse cosine is also known as :math:`arccos` or :math:`cos^{-1}`. +The inverse cosine is also known as :math:`cos^{-1}`. Examples -------- @@ -229,11 +229,11 @@ def _get_accumulation_res_dt(a, dtype): See Also -------- :obj:`dpnp.cosh` : Hyperbolic cosine, element-wise. -:obj:`dpnp.arcsinh` : Hyperbolic inverse sine, element-wise. +:obj:`dpnp.asinh` : Hyperbolic inverse sine, element-wise. :obj:`dpnp.sinh` : Hyperbolic sine, element-wise. -:obj:`dpnp.arctanh` : Hyperbolic inverse tangent, element-wise. +:obj:`dpnp.atanh` : Hyperbolic inverse tangent, element-wise. :obj:`dpnp.tanh` : Hyperbolic tangent, element-wise. -:obj:`dpnp.arccos` : Trigonometric inverse cosine, element-wise. +:obj:`dpnp.acos` : Trigonometric inverse cosine, element-wise. Notes ----- @@ -250,8 +250,7 @@ def _get_accumulation_res_dt(a, dtype): analytic function that has, by convention, the branch cuts :math:`(-\infty, 1]` and is continuous from above on it. -The inverse hyperbolic cosine is also known as :math:`arccosh` or -:math:`cosh^{-1}`. +The inverse hyperbolic cosine is also known as :math:`cosh^{-1}`. Examples -------- From 9abce323236a1990008f7ed6ff7186cd578016db Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Wed, 2 Apr 2025 18:15:46 +0200 Subject: [PATCH 08/32] Update docstring of `asin` and `asinh` function to use math where applicable. Also `arcsin` is now alias on `asin` function. And `arcsinh` is now alias on `asinh` function. --- dpnp/dpnp_iface_trigonometric.py | 108 ++++++++++++++++--------------- 1 file changed, 56 insertions(+), 52 deletions(-) diff --git a/dpnp/dpnp_iface_trigonometric.py b/dpnp/dpnp_iface_trigonometric.py index d1b1c341697b..e8d01aae0071 100644 --- a/dpnp/dpnp_iface_trigonometric.py +++ b/dpnp/dpnp_iface_trigonometric.py @@ -274,17 +274,17 @@ def _get_accumulation_res_dt(a, dtype): _ASIN_DOCSTRING = r""" -Computes inverse sine for each element `x_i` for input array `x`. +Computes inverse sine for each element :math:`x_i` for input array `x`. -The inverse of :obj:`dpnp.sin`, so that if ``y = sin(x)`` then ``x = arcsin(y)``. -Note that :obj:`dpnp.asin` is an alias of :obj:`dpnp.arcsin`. +The inverse of :obj:`dpnp.sin`, so that if :math:`y = sin(x)` then +:math:`x = asin(y)`. Note that :obj:`dpnp.arcsin` is an alias of :obj:`dpnp.asin`. -For full documentation refer to :obj:`numpy.arcsin`. +For full documentation refer to :obj:`numpy.asin`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + Input array, expected to have a floating-point data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -298,9 +298,9 @@ def _get_accumulation_res_dt(a, dtype): Returns ------- out : dpnp.ndarray - An array containing the element-wise inverse sine, in radians - and in the closed interval `[-\pi/2, \pi/2]`. The data type - of the returned array is determined by the Type Promotion Rules. + An array containing the element-wise inverse sine, in radians and in the + closed interval :math:`[-\pi/2, \pi/2]`. The data type of the returned + array is determined by the Type Promotion Rules. Limitations ----------- @@ -312,39 +312,41 @@ def _get_accumulation_res_dt(a, dtype): -------- :obj:`dpnp.sin` : Trigonometric sine, element-wise. :obj:`dpnp.cos` : Trigonometric cosine, element-wise. -:obj:`dpnp.arccos` : Trigonometric inverse cosine, element-wise. +:obj:`dpnp.acos` : Trigonometric inverse cosine, element-wise. :obj:`dpnp.tan` : Trigonometric tangent, element-wise. -:obj:`dpnp.arctan` : Trigonometric inverse tangent, element-wise. -:obj:`dpnp.arctan2` : Element-wise arc tangent of `x1/x2` choosing the quadrant correctly. -:obj:`dpnp.arcsinh` : Hyperbolic inverse sine, element-wise. +:obj:`dpnp.atan` : Trigonometric inverse tangent, element-wise. +:obj:`dpnp.atan2` : Element-wise arc tangent of `x1/x2` + choosing the quadrant correctly. +:obj:`dpnp.asinh` : Hyperbolic inverse sine, element-wise. Notes ----- -:obj:`dpnp.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]`. +:obj:`dpnp.asin` is a multivalued function: for each `x` there are infinitely +many numbers `z` such that :math:`sin(z) = x`. The convention is to return the +angle `z` whose the real part lies in the interval :math:`[-\pi/2, \pi/2]`. -For real-valued input data types, :obj:`dpnp.arcsin` always returns real output. -For each value that cannot be expressed as a real number or infinity, it yields -``NaN``. +For real-valued floating-point input data types, :obj:`dpnp.asin` always +returns real output. For each value that cannot be expressed as a real number +or infinity, it yields ``NaN``. -For complex-valued input, :obj:`dpnp.arcsin` is a complex analytic function that -has, by convention, the branch cuts `[-\infty, -1]` and `[1, \infty]` and is continuous -from above on the former and from below on the latter. +For complex floating-point input data types, :obj:`dpnp.asin` is a complex +analytic function that has, by convention, the branch cuts +:math:`(-\infty, -1]` and :math:`[1, \infty)` and is continuous from above on +the former and from below on the latter. -The inverse sine is also known as :math:`asin` or :math:`sin^{-1}`. +The inverse sine is also known as :math:`sin^{-1}`. Examples -------- >>> import dpnp as np >>> x = np.array([0, 1, -1]) ->>> np.arcsin(x) +>>> np.asin(x) array([0.0, 1.5707963267948966, -1.5707963267948966]) """ -arcsin = DPNPUnaryFunc( - "arcsin", +asin = DPNPUnaryFunc( + "asin", ti._asin_result_type, ti._asin, _ASIN_DOCSTRING, @@ -352,21 +354,23 @@ def _get_accumulation_res_dt(a, dtype): mkl_impl_fn="_asin", ) -asin = arcsin # asin is an alias for arcsin +arcsin = asin # arcsin is an alias for asin _ASINH_DOCSTRING = r""" -Computes inverse hyperbolic sine for each element `x_i` for input array `x`. +Computes inverse hyperbolic sine for each element :math:`x_i` for input array +`x`. -The inverse of :obj:`dpnp.sinh`, so that if ``y = sinh(x)`` then ``x = arcsinh(y)``. -Note that :obj:`dpnp.asinh` is an alias of :obj:`dpnp.arcsinh`. +The inverse of :obj:`dpnp.sinh`, so that if :math:`y = sinh(x)` then +:math:`x = asinh(y)`. Note that :obj:`dpnp.arcsinh` is an alias of +:obj:`dpnp.asinh`. -For full documentation refer to :obj:`numpy.arcsinh`. +For full documentation refer to :obj:`numpy.asinh`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + Input array, expected to have a floating-point data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -380,9 +384,9 @@ def _get_accumulation_res_dt(a, dtype): Returns ------- out : dpnp.ndarray - An array containing the element-wise inverse hyperbolic sine. - The data type of the returned array is determined by - the Type Promotion Rules. + An array containing the element-wise inverse hyperbolic sine, in radians. + The data type of the returned array is determined by the Type Promotion + Rules. Limitations ----------- @@ -393,38 +397,38 @@ def _get_accumulation_res_dt(a, dtype): See Also -------- :obj:`dpnp.sinh` : Hyperbolic sine, element-wise. -:obj:`dpnp.arctanh` : Hyperbolic inverse tangent, element-wise. -:obj:`dpnp.arccosh` : Hyperbolic inverse cosine, element-wise. -:obj:`dpnp.arcsin` : Trigonometric inverse sine, element-wise. +:obj:`dpnp.atanh` : Hyperbolic inverse tangent, element-wise. +:obj:`dpnp.acosh` : Hyperbolic inverse cosine, element-wise. +:obj:`dpnp.asin` : Trigonometric inverse sine, element-wise. Notes ----- -:obj:`dpnp.arcsinh` 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]`. - -For real-valued input data types, :obj:`dpnp.arcsinh` always returns real output. -For each value that cannot be expressed as a real number or infinity, it yields -``NaN``. +:obj:`dpnp.asinh` is a multivalued function: for each `x` there are infinitely +many numbers `z` such that :math:`sin(z) = x`. The convention is to return the +angle `z` whose the imaginary part lies in the interval :math:`[-\pi/2, \pi/2]`. -For complex-valued input, :obj:`dpnp.arcsinh` is a complex analytic function that -has, by convention, the branch cuts `[1j, infj]` and `[`1j, -infj]` and is continuous -from above on the former and from below on the latter. +For real-valued floating-point input data types, :obj:`dpnp.asinh` always +returns real output. For each value that cannot be expressed as a real number +or infinity, it yields ``NaN``. -The inverse hyperbolic sine is also known as :math:`asinh` or :math:`sinh^{-1}`. +For complex floating-point input data types, :obj:`dpnp.asinh` is a complex +analytic function that has, by convention, the branch cuts +:math:`(-\inftyj, -j]` and :math:`[j, \inftyj)` and is continuous from the left +on the former and from the right on the latter. +The inverse hyperbolic sine is also known as :math:`sinh^{-1}`. Examples -------- >>> import dpnp as np >>> x = np.array([np.e, 10.0]) ->>> np.arcsinh(x) +>>> np.asinh(x) array([1.72538256, 2.99822295]) """ -arcsinh = DPNPUnaryFunc( - "arcsinh", +asinh = DPNPUnaryFunc( + "asinh", ti._asinh_result_type, ti._asinh, _ASINH_DOCSTRING, @@ -432,7 +436,7 @@ def _get_accumulation_res_dt(a, dtype): mkl_impl_fn="_asinh", ) -asinh = arcsinh # asinh is an alias for arcsinh +arcsinh = asinh # arcsinh is an alias for asinh _ATAN_DOCSTRING = r""" From 4f39caa623be4cd318444c2dd7abef4f548175aa Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Wed, 2 Apr 2025 19:04:06 +0200 Subject: [PATCH 09/32] Update branch cuts intervals in acos, acosh, asin, and asinh --- dpnp/dpnp_iface_trigonometric.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/dpnp/dpnp_iface_trigonometric.py b/dpnp/dpnp_iface_trigonometric.py index e8d01aae0071..0d21b7d2a235 100644 --- a/dpnp/dpnp_iface_trigonometric.py +++ b/dpnp/dpnp_iface_trigonometric.py @@ -163,7 +163,7 @@ def _get_accumulation_res_dt(a, dtype): For complex floating-point input data types, :obj:`dpnp.acos` is a complex analytic function that has, by convention, the branch cuts -:math:`(-\infty, -1]` and :math:`[1, \infty)` and is continuous from above on +:math:`(-\infty, -1)` and :math:`(1, \infty)` and is continuous from above on the former and from below on the latter. The inverse cosine is also known as :math:`cos^{-1}`. @@ -247,7 +247,7 @@ def _get_accumulation_res_dt(a, dtype): or infinity, it yields ``NaN``. For complex floating-point input data types, :obj:`dpnp.acosh` is a complex -analytic function that has, by convention, the branch cuts :math:`(-\infty, 1]` +analytic function that has, by convention, the branch cuts :math:`(-\infty, 1)` and is continuous from above on it. The inverse hyperbolic cosine is also known as :math:`cosh^{-1}`. @@ -331,7 +331,7 @@ def _get_accumulation_res_dt(a, dtype): For complex floating-point input data types, :obj:`dpnp.asin` is a complex analytic function that has, by convention, the branch cuts -:math:`(-\infty, -1]` and :math:`[1, \infty)` and is continuous from above on +:math:`(-\infty, -1)` and :math:`(1, \infty)` and is continuous from above on the former and from below on the latter. The inverse sine is also known as :math:`sin^{-1}`. @@ -413,7 +413,7 @@ def _get_accumulation_res_dt(a, dtype): For complex floating-point input data types, :obj:`dpnp.asinh` is a complex analytic function that has, by convention, the branch cuts -:math:`(-\inftyj, -j]` and :math:`[j, \inftyj)` and is continuous from the left +:math:`(-\infty j, -j)` and :math:`(j, \infty j)` and is continuous from the left on the former and from the right on the latter. The inverse hyperbolic sine is also known as :math:`sinh^{-1}`. From bc879bfc8225f029564367156d006fe5fee7a0fa Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Wed, 2 Apr 2025 19:14:40 +0200 Subject: [PATCH 10/32] Update docstring of `atan`, `atan2`, and `atanh` functions to use math where applicable. Also `arctan` is now alias on `atan` function. And `arctan2` is now alias on `atan2` function. And `arctanh` is now alias on `atanh` function. --- dpnp/dpnp_iface_trigonometric.py | 162 ++++++++++++++++--------------- 1 file changed, 85 insertions(+), 77 deletions(-) diff --git a/dpnp/dpnp_iface_trigonometric.py b/dpnp/dpnp_iface_trigonometric.py index 0d21b7d2a235..9e6130e23847 100644 --- a/dpnp/dpnp_iface_trigonometric.py +++ b/dpnp/dpnp_iface_trigonometric.py @@ -440,17 +440,18 @@ def _get_accumulation_res_dt(a, dtype): _ATAN_DOCSTRING = r""" -Computes inverse tangent for each element `x_i` for input array `x`. +Computes inverse tangent for each element :math:`x_i` for input array `x`. -The inverse of :obj:`dpnp.tan`, so that if ``y = tan(x)`` then ``x = arctan(y)``. -Note that :obj:`dpnp.atan` is an alias of :obj:`dpnp.arctan`. +The inverse of :obj:`dpnp.tan`, so that if :math:`y = tan(x)` then +:math:`x = atan(y)`. Note that :obj:`dpnp.arctan` is an alias of +:obj:`dpnp.atan`. -For full documentation refer to :obj:`numpy.arctan`. +For full documentation refer to :obj:`numpy.atan`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + Input array, expected to have a floating-point data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -464,9 +465,9 @@ def _get_accumulation_res_dt(a, dtype): Returns ------- out : dpnp.ndarray - An array containing the element-wise inverse tangent, in radians - and in the closed interval `[-\pi/2, \pi/2]`. The data type - of the returned array is determined by the Type Promotion Rules. + An array containing the element-wise inverse tangent, in radians and in the + closed interval :math:`[-\pi/2, \pi/2]`. The data type of the returned + array is determined by the Type Promotion Rules. Limitations ----------- @@ -476,40 +477,42 @@ def _get_accumulation_res_dt(a, dtype): See Also -------- -:obj:`dpnp.arctan2` : Element-wise arc tangent of `x1/x2` choosing the quadrant correctly. +:obj:`dpnp.atan2` : Element-wise arc tangent of `x1/x2` + choosing the quadrant correctly. :obj:`dpnp.angle` : Argument of complex values. :obj:`dpnp.tan` : Trigonometric tangent, element-wise. -:obj:`dpnp.arcsin` : Trigonometric inverse sine, element-wise. -:obj:`dpnp.arccos` : Trigonometric inverse cosine, element-wise. -:obj:`dpnp.arctanh` : Inverse hyperbolic tangent, element-wise. +:obj:`dpnp.asin` : Trigonometric inverse sine, element-wise. +:obj:`dpnp.acos` : Trigonometric inverse cosine, element-wise. +:obj:`dpnp.atanh` : Inverse hyperbolic tangent, element-wise. Notes ----- -:obj:`dpnp.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]`. +:obj:`dpnp.atan` is a multivalued function: for each `x` there are infinitely +many numbers `z` such that :math:`tan(z) = x`. The convention is to return the +angle `z` whose the real part lies in the interval :math:`[-\pi/2, \pi/2]`. -For real-valued input data types, :obj:`dpnp.arctan` always returns real output. -For each value that cannot be expressed as a real number or infinity, it yields -``NaN``. +For real-valued floating-point input data types, :obj:`dpnp.atan` always +returns real output. For each value that cannot be expressed as a real number +or infinity, it yields ``NaN``. -For complex-valued input, :obj:`dpnp.arctan` is a complex analytic function that -has, by convention, the 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 floating-point input data types, :obj:`dpnp.atan` is a complex +analytic function that has, by convention, the branch cuts +:math:`(-\infty j, -j)` and :math:`(j, \infty j)` and is continuous from the right +on the former and from the left on the latter. -The inverse tan is also known as :math:`atan` or :math:`tan^{-1}`. +The inverse tangent is also known as :math:`tan^{-1}`. Examples -------- >>> import dpnp as np >>> x = np.array([0, 1]) ->>> np.arctan(x) +>>> np.atan(x) array([0.0, 0.78539816]) """ -arctan = DPNPUnaryFunc( - "arctan", +atan = DPNPUnaryFunc( + "atan", ti._atan_result_type, ti._atan, _ATAN_DOCSTRING, @@ -517,32 +520,27 @@ def _get_accumulation_res_dt(a, dtype): mkl_impl_fn="_atan", ) -atan = arctan # atan is an alias for arctan +arctan = atan # arctan is an alias for atan _ATAN2_DOCSTRING = """ -Calculates the inverse tangent of the quotient `x1_i/x2_i` for each element -`x1_i` of the input array `x1` with the respective element `x2_i` of the -input array `x2`. Each element-wise result is expressed in radians. +Calculates the inverse tangent of the quotient :math:`x1_i/x2_i` for each +element :math:`x1_i` of the input array `x1` with the respective element +:math:`x2_i` of the input array `x2`. -Note that :obj:`dpnp.atan2` is an alias of :obj:`dpnp.arctan2`. +Note that :obj:`dpnp.arctan2` is an alias of :obj:`dpnp.atan2`. This function is not defined for complex-valued arguments; for the so-called argument of complex values, use :obj:`dpnp.angle`. -For full documentation refer to :obj:`numpy.arctan2`. +For full documentation refer to :obj:`numpy.atan2`. Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have a real-valued floating-point - data type. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, expected to have a real-valued floating-point data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have a real-valued - floating-point data type. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also expected to have a real-valued floating-point data + type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -556,9 +554,9 @@ def _get_accumulation_res_dt(a, dtype): Returns ------- out : dpnp.ndarray - An array containing the inverse tangent of the quotient `x1`/`x2`. - The returned array must have a real-valued floating-point data type - determined by Type Promotion Rules. + An array containing the inverse tangent of the quotient :math:`x1/x2`, in + radians. The returned array must have a real-valued floating-point data + type determined by Type Promotion Rules. Limitations ----------- @@ -568,35 +566,42 @@ def _get_accumulation_res_dt(a, dtype): See Also -------- -:obj:`dpnp.arctan` : Trigonometric inverse tangent, element-wise. +:obj:`dpnp.atan` : Trigonometric inverse tangent, element-wise. :obj:`dpnp.tan` : Compute tangent element-wise. :obj:`dpnp.angle` : Return the angle of the complex argument. -:obj:`dpnp.arcsin` : Trigonometric inverse sine, element-wise. -:obj:`dpnp.arccos` : Trigonometric inverse cosine, element-wise. -:obj:`dpnp.arctanh` : Inverse hyperbolic tangent, element-wise. +:obj:`dpnp.asin` : Trigonometric inverse sine, element-wise. +:obj:`dpnp.acos` : Trigonometric inverse cosine, element-wise. +:obj:`dpnp.atanh` : Inverse hyperbolic tangent, element-wise. + +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). Examples -------- >>> import dpnp as np >>> x1 = np.array([1., -1.]) >>> x2 = np.array([0., 0.]) ->>> np.arctan2(x1, x2) +>>> np.atan2(x1, x2) array([1.57079633, -1.57079633]) >>> x1 = np.array([0., 0., np.inf]) >>> x2 = np.array([+0., -0., np.inf]) ->>> np.arctan2(x1, x2) +>>> np.atan2(x1, x2) array([0.0 , 3.14159265, 0.78539816]) >>> x1 = np.array([-1, +1, +1, -1]) >>> x2 = np.array([-1, -1, +1, +1]) ->>> np.arctan2(x1, x2) * 180 / np.pi +>>> np.atan2(x1, x2) * 180 / np.pi array([-135., -45., 45., 135.]) """ -arctan2 = DPNPBinaryFunc( - "arctan2", +atan2 = DPNPBinaryFunc( + "atan2", ti._atan2_result_type, ti._atan2, _ATAN2_DOCSTRING, @@ -604,21 +609,23 @@ def _get_accumulation_res_dt(a, dtype): mkl_impl_fn="_atan2", ) -atan2 = arctan2 # atan2 is an alias for arctan2 +arctan2 = atan2 # arctan2 is an alias for atan2 _ATANH_DOCSTRING = r""" -Computes hyperbolic inverse tangent for each element `x_i` for input array `x`. +Computes hyperbolic inverse tangent for each element :math:`x_i` for input +array `x`. -The inverse of :obj:`dpnp.tanh`, so that if ``y = tanh(x)`` then ``x = arctanh(y)``. -Note that :obj:`dpnp.atanh` is an alias of :obj:`dpnp.arctanh`. +The inverse of :obj:`dpnp.tanh`, so that if :math:`y = tanh(x)` then +:math:`x = atanh(y)`. Note that :obj:`dpnp.arctanh` is an alias of +:obj:`dpnp.atanh`. -For full documentation refer to :obj:`numpy.arctanh`. +For full documentation refer to :obj:`numpy.atanh`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + Input array, expected to have a floating-point data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -632,9 +639,9 @@ def _get_accumulation_res_dt(a, dtype): Returns ------- out : dpnp.ndarray - An array containing the element-wise hyperbolic inverse tangent. - The data type of the returned array is determined by - the Type Promotion Rules. + An array containing the element-wise inverse hyperbolic tangent, in + radians. The data type of the returned array is determined by the Type + Promotion Rules. Limitations ----------- @@ -645,37 +652,38 @@ def _get_accumulation_res_dt(a, dtype): See Also -------- :obj:`dpnp.tanh` : Hyperbolic tangent, element-wise. -:obj:`dpnp.arcsinh` : Hyperbolic inverse sine, element-wise. -:obj:`dpnp.arccosh` : Hyperbolic inverse cosine, element-wise. -:obj:`dpnp.arctan` : Trigonometric inverse tangent, element-wise. +:obj:`dpnp.asinh` : Hyperbolic inverse sine, element-wise. +:obj:`dpnp.acosh` : Hyperbolic inverse cosine, element-wise. +:obj:`dpnp.atan` : Trigonometric inverse tangent, element-wise. Notes ----- -:obj:`dpnp.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 -angle `z` whose real part lies in `[-\pi/2, \pi/2]`. +:obj:`dpnp.atanh` is a multivalued function: for each `x` there are infinitely +many numbers `z` such that :math:`tanh(z) = x`. The convention is to return the +angle `z` whose the imaginary part lies in the interval :math:`[-\pi/2, \pi/2]`. -For real-valued input data types, :obj:`dpnp.arctanh` always returns real output. -For each value that cannot be expressed as a real number or infinity, it yields -``NaN``. +For real-valued floating-point input data types, :obj:`dpnp.atanh` always +returns real output. For each value that cannot be expressed as a real number +or infinity, it yields ``NaN``. -For complex-valued input, :obj:`dpnp.arctanh` is a complex analytic function that -has, by convention, the branch cuts `[-1, -\infty]` and `[1, \infty]` and is is continuous -from above on the former and from below on the latter. +For complex floating-point input data types, :obj:`dpnp.atanh` is a complex +analytic function that has, by convention, the branch cuts +:math:`(-\infty, -1]` and :math:`[1, \infty)` and is continuous from above on +the former and from below on the latter. -The inverse hyperbolic tan is also known as :math:`atanh` or :math:`tanh^{-1}`. +The inverse hyperbolic tangent is also known as :math:`tanh^{-1}`. Examples -------- >>> import dpnp as np >>> x = np.array([0, -0.5]) ->>> np.arctanh(x) +>>> np.atanh(x) array([0.0, -0.54930614]) """ -arctanh = DPNPUnaryFunc( - "arctanh", +atanh = DPNPUnaryFunc( + "atanh", ti._atanh_result_type, ti._atanh, _ATANH_DOCSTRING, @@ -683,7 +691,7 @@ def _get_accumulation_res_dt(a, dtype): mkl_impl_fn="_atanh", ) -atanh = arctanh # atanh is an alias for arctanh +arctanh = atanh # arctanh is an alias for atanh _CBRT_DOCSTRING = """ From 926c203a810991c2fa59db3ee82a41551c7ecf22 Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Wed, 2 Apr 2025 20:10:26 +0200 Subject: [PATCH 11/32] Remove unnecessary reruning of tests in testing MKL interfaces GH action --- .github/workflows/check-mkl-interfaces.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/check-mkl-interfaces.yaml b/.github/workflows/check-mkl-interfaces.yaml index fb294e7c4929..3d89716c6630 100644 --- a/.github/workflows/check-mkl-interfaces.yaml +++ b/.github/workflows/check-mkl-interfaces.yaml @@ -229,7 +229,7 @@ jobs: python -c "import dpnp; print(dpnp.__version__)" - name: Run tests - if: env.rerun-tests-on-failure == 'true' + if: env.rerun-tests-on-failure != 'true' run: | python -m pytest -ra --pyargs dpnp.tests env: From 378d252cd7a69de92cf9584483f0e3f8940af92b Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Wed, 2 Apr 2025 20:16:34 +0200 Subject: [PATCH 12/32] Update docstring of `cbrt` function --- dpnp/dpnp_iface_trigonometric.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/dpnp/dpnp_iface_trigonometric.py b/dpnp/dpnp_iface_trigonometric.py index 9e6130e23847..337d23909281 100644 --- a/dpnp/dpnp_iface_trigonometric.py +++ b/dpnp/dpnp_iface_trigonometric.py @@ -695,14 +695,14 @@ def _get_accumulation_res_dt(a, dtype): _CBRT_DOCSTRING = """ -Computes positive cube-root for each element `x_i` for input array `x`. +Computes positive cube-root for each element :math:`x_i` for input array `x`. For full documentation refer to :obj:`numpy.cbrt`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have a real-valued data type. + Input array, expected to have a real floating-point data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -717,8 +717,8 @@ def _get_accumulation_res_dt(a, dtype): ------- out : dpnp.ndarray An array containing the element-wise positive cube-root. - The data type of the returned array is determined by - the Type Promotion Rules. + The data type of the returned array is determined by the Type Promotion + Rules. Limitations ----------- From 335d0f8221a10210765315e5365e389905bf7536 Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Wed, 2 Apr 2025 20:27:43 +0200 Subject: [PATCH 13/32] Update docstring of `cos` and `cosh` function to use math where applicable. --- dpnp/dpnp_iface_trigonometric.py | 26 +++++++++++++++----------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/dpnp/dpnp_iface_trigonometric.py b/dpnp/dpnp_iface_trigonometric.py index 337d23909281..b3637f7c46ba 100644 --- a/dpnp/dpnp_iface_trigonometric.py +++ b/dpnp/dpnp_iface_trigonometric.py @@ -750,14 +750,14 @@ def _get_accumulation_res_dt(a, dtype): _COS_DOCSTRING = """ -Computes cosine for each element `x_i` for input array `x`. +Computes cosine for each element :math:`x_i` for input array `x`. For full documentation refer to :obj:`numpy.cos`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + Input array, expected to have a floating-point data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -771,8 +771,8 @@ def _get_accumulation_res_dt(a, dtype): Returns ------- out : dpnp.ndarray - An array containing the element-wise cosine. The data type - of the returned array is determined by the Type Promotion Rules. + An array containing the element-wise cosine. The data type of the returned + array is determined by the Type Promotion Rules. Limitations ----------- @@ -782,7 +782,7 @@ def _get_accumulation_res_dt(a, dtype): See Also -------- -:obj:`dpnp.arccos` : Trigonometric inverse cosine, element-wise. +:obj:`dpnp.acos` : Trigonometric inverse cosine, element-wise. :obj:`dpnp.sin` : Trigonometric sine, element-wise. :obj:`dpnp.tan` : Trigonometric tangent, element-wise. :obj:`dpnp.cosh` : Hyperbolic cosine, element-wise. @@ -806,15 +806,19 @@ def _get_accumulation_res_dt(a, dtype): ) -_COSH_DOCSTRING = """ -Computes hyperbolic cosine for each element `x_i` for input array `x`. +_COSH_DOCSTRING = r""" +Computes hyperbolic cosine for each element :math:`x_i` for input array `x`. + +The mathematical definition of the hyperbolic cosine is + +.. math:: \operatorname{cosh}(x) = \frac{e^x + e^{-x}}{2} For full documentation refer to :obj:`numpy.cosh`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + Input array, expected to have a floating-point data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -828,8 +832,8 @@ def _get_accumulation_res_dt(a, dtype): Returns ------- out : dpnp.ndarray - An array containing the element-wise hyperbolic cosine. The data type - of the returned array is determined by the Type Promotion Rules. + An array containing the element-wise hyperbolic cosine. The data type of + the returned array is determined by the Type Promotion Rules. Limitations ----------- @@ -839,7 +843,7 @@ def _get_accumulation_res_dt(a, dtype): See Also -------- -:obj:`dpnp.arccosh` : Hyperbolic inverse cosine, element-wise. +:obj:`dpnp.acosh` : Hyperbolic inverse cosine, element-wise. :obj:`dpnp.sinh` : Hyperbolic sine, element-wise. :obj:`dpnp.tanh` : Hyperbolic tangent, element-wise. :obj:`dpnp.cos` : Trigonometric cosine, element-wise. From ef8be1d0e42a5d09d5badc3f3df027b7fb176796 Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Wed, 2 Apr 2025 20:33:22 +0200 Subject: [PATCH 14/32] Replace `real floating-point` with `real-valued floating-point` per array API spec --- dpnp/dpnp_iface_mathematical.py | 4 ++-- dpnp/dpnp_iface_trigonometric.py | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/dpnp/dpnp_iface_mathematical.py b/dpnp/dpnp_iface_mathematical.py index dc2dd9c41da7..81245f60dc5b 100644 --- a/dpnp/dpnp_iface_mathematical.py +++ b/dpnp/dpnp_iface_mathematical.py @@ -800,10 +800,10 @@ def clip(a, /, min=None, max=None, *, out=None, order="K", **kwargs): Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have a real floating-point data type. + First input array, expected to have a real-valued floating-point data type. Both inputs `x1` and `x2` can not be scalars at the same time. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have a real floating-point data + Second input array, also expected to have a real-valued floating-point data type. Both inputs `x1` and `x2` can not be scalars at the same time. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape diff --git a/dpnp/dpnp_iface_trigonometric.py b/dpnp/dpnp_iface_trigonometric.py index b3637f7c46ba..16471d6edefc 100644 --- a/dpnp/dpnp_iface_trigonometric.py +++ b/dpnp/dpnp_iface_trigonometric.py @@ -702,7 +702,7 @@ def _get_accumulation_res_dt(a, dtype): Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have a real floating-point data type. + Input array, expected to have a real-valued floating-point data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -2075,7 +2075,7 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have a real floating-point data type. + Input array, expected to have a real-valued floating-point data type. out : {None, dpnp.ndarray, usm_ndarray}, optional: Output array to populate. Array must have the correct shape and the expected data type. From 870570aa2e01e33aa1dea7260ed3f51e6fca6333 Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Wed, 2 Apr 2025 20:38:00 +0200 Subject: [PATCH 15/32] Replace `real-valued` with `real-valued floating-point` per array API spec --- dpnp/dpnp_iface_mathematical.py | 22 +++++++++++----------- dpnp/dpnp_iface_trigonometric.py | 10 +++++----- 2 files changed, 16 insertions(+), 16 deletions(-) diff --git a/dpnp/dpnp_iface_mathematical.py b/dpnp/dpnp_iface_mathematical.py index 81245f60dc5b..a071351c10a3 100644 --- a/dpnp/dpnp_iface_mathematical.py +++ b/dpnp/dpnp_iface_mathematical.py @@ -372,7 +372,7 @@ def _process_ediff1d_args(arg, arg_name, ary_dtype, ary_sycl_queue, usm_type): out : dpnp.ndarray An array containing the element-wise absolute values. For complex input, the absolute value is its magnitude. - If `x` has a real-valued data type, the returned array has the + If `x` has a real-valued floating-point data type, the returned array has the same data type as `x`. If `x` has a complex floating-point data type, the returned array has a real-valued floating-point data type whose precision matches the precision of `x`. @@ -611,7 +611,7 @@ def around(x, /, decimals=0, out=None): Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have a real-valued data type. + Input array, expected to have a real-valued floating-point data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -1719,7 +1719,7 @@ def ediff1d(ary, to_end=None, to_begin=None): Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have a real-valued data type. + Input array, expected to have a real-valued floating-point data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -1880,7 +1880,7 @@ def ediff1d(ary, to_end=None, to_begin=None): Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have a real-valued data type. + Input array, expected to have a real-valued floating-point data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -2197,10 +2197,10 @@ def ediff1d(ary, to_end=None, to_begin=None): Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have a real-valued data type. + First input array, expected to have a real-valued floating-point data type. Both inputs `x1` and `x2` can not be scalars at the same time. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have a real-valued data type. + Second input array, also expected to have a real-valued floating-point data type. Both inputs `x1` and `x2` can not be scalars at the same time. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). @@ -2654,7 +2654,7 @@ def gradient(f, *varargs, axis=None, edge_order=1): ------- out : dpnp.ndarray An array containing the element-wise imaginary component of input. - If the input is a real-valued data type, the returned array has + If the input is a real-valued floating-point data type, the returned array has the same data type. If the input is a complex floating-point data type, the returned array has a floating-point data type with the same floating-point precision as complex input. @@ -3693,7 +3693,7 @@ def prod( ------- out : dpnp.ndarray An array containing the element-wise real component of input. - If the input is a real-valued data type, the returned array has + If the input is a real-valued floating-point data type, the returned array has the same data type. If the input is a complex floating-point data type, the returned array has a floating-point data type with the same floating-point precision as complex input. @@ -3804,10 +3804,10 @@ def real_if_close(a, tol=100): Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have a real-valued data type. + First input array, expected to have a real-valued floating-point data type. Both inputs `x1` and `x2` can not be scalars at the same time. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have a real-valued data type. + Second input array, also expected to have a real-valued floating-point data type. Both inputs `x1` and `x2` can not be scalars at the same time. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). @@ -4553,7 +4553,7 @@ def trapezoid(y, x=None, dx=1.0, axis=-1): Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have a real-valued data type. + Input array, expected to have a real-valued floating-point data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. diff --git a/dpnp/dpnp_iface_trigonometric.py b/dpnp/dpnp_iface_trigonometric.py index 16471d6edefc..bba1b7f6c2c3 100644 --- a/dpnp/dpnp_iface_trigonometric.py +++ b/dpnp/dpnp_iface_trigonometric.py @@ -878,7 +878,7 @@ def cumlogsumexp( Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have a real-valued data type. + Input array, expected to have a real-valued floating-point data type. axis : {None, int}, optional Axis or axes along which values must be computed. If a tuple of unique integers, values are computed over multiple axes. If ``None``, the @@ -1266,10 +1266,10 @@ def cumlogsumexp( Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have a real-valued data type. + First input array, expected to have a real-valued floating-point data type. Both inputs `x1` and `x2` can not be scalars at the same time. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have a real-valued data type. + Second input array, also expected to have a real-valued floating-point data type. Both inputs `x1` and `x2` can not be scalars at the same time. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). @@ -1730,7 +1730,7 @@ def logsumexp(x, /, *, axis=None, dtype=None, keepdims=False, out=None): Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have a real-valued data type. + Input array, expected to have a real-valued floating-point data type. axis : {None, int or tuple of ints}, optional Axis or axes along which values must be computed. If a tuple of unique integers, values are computed over multiple axes. If ``None``, the @@ -1992,7 +1992,7 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have a real-valued data type. + Input array, expected to have a real-valued floating-point data type. axis : {None, int or tuple of ints}, optional Axis or axes along which values must be computed. If a tuple of unique integers, values are computed over multiple axes. If ``None``, the From be87542ec68803867ea33b7a9c398d4a9acdda0f Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Wed, 2 Apr 2025 20:45:05 +0200 Subject: [PATCH 16/32] Update docstring of `cumlogsumexp` function --- dpnp/dpnp_iface_trigonometric.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dpnp/dpnp_iface_trigonometric.py b/dpnp/dpnp_iface_trigonometric.py index bba1b7f6c2c3..56bce689bdef 100644 --- a/dpnp/dpnp_iface_trigonometric.py +++ b/dpnp/dpnp_iface_trigonometric.py @@ -878,7 +878,7 @@ def cumlogsumexp( Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have a real-valued floating-point data type. + Input array, expected to have a boolean or real-valued data type. axis : {None, int}, optional Axis or axes along which values must be computed. If a tuple of unique integers, values are computed over multiple axes. If ``None``, the From 3e02fbf422ca0b6fdf1f499f40b0def75fa8956c Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Wed, 2 Apr 2025 21:16:08 +0200 Subject: [PATCH 17/32] Update docstring of `deg2rad`, `rad2deg`, `radians`, and `degrees` functions to use math where applicable --- dpnp/dpnp_iface_trigonometric.py | 68 +++++++++++++++++++++----------- 1 file changed, 46 insertions(+), 22 deletions(-) diff --git a/dpnp/dpnp_iface_trigonometric.py b/dpnp/dpnp_iface_trigonometric.py index 56bce689bdef..6178886cdbfe 100644 --- a/dpnp/dpnp_iface_trigonometric.py +++ b/dpnp/dpnp_iface_trigonometric.py @@ -960,15 +960,16 @@ def cumlogsumexp( ) -_DEG2RAD_DOCSTRING = """ -Convert angles from degrees to radians. +_DEG2RAD_DOCSTRING = r""" +Convert angles from degrees to radians for each element :math:`x_i` for input +array `x`. For full documentation refer to :obj:`numpy.deg2rad`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Angles in degrees. + Input array, expected to have a real-valued floating-point data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -982,8 +983,9 @@ def cumlogsumexp( Returns ------- out : dpnp.ndarray - The corresponding angle in radians. The data type of the returned array is - determined by the Type Promotion Rules. + An array containing the element-wise angle in radians. + The data type of the returned array is determined by the Type Promotion + Rules. Limitations ----------- @@ -999,7 +1001,9 @@ def cumlogsumexp( Notes ----- -dpnp.deg2rad(x) is ``x * pi / 180``. +The mathematical definition is + +.. math:: \operatorname{deg2rad}(x) = \frac{x * \pi}{180} Examples -------- @@ -1018,15 +1022,16 @@ def cumlogsumexp( ) -_DEGREES_DOCSTRING = """ -Convert angles from radians to degrees. +_DEGREES_DOCSTRING = r""" +Convert angles from degrees to radians for each element :math:`x_i` for input +array `x`. For full documentation refer to :obj:`numpy.degrees`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array in radians. + Input array, expected to have a real-valued floating-point data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -1040,8 +1045,9 @@ def cumlogsumexp( Returns ------- out : dpnp.ndarray - The corresponding degree values. The data type of the returned array is - determined by the Type Promotion Rules. + An array containing the element-wise angle in degrees. + The data type of the returned array is determined by the Type Promotion + Rules. Limitations ----------- @@ -1053,6 +1059,12 @@ def cumlogsumexp( -------- :obj:`dpnp.rad2deg` : Equivalent function. +Notes +----- +The mathematical definition is + +.. math:: \operatorname{degrees}(x) = \frac{180 * x}{\pi} + Examples -------- >>> import dpnp as np @@ -1811,15 +1823,16 @@ def logsumexp(x, /, *, axis=None, dtype=None, keepdims=False, out=None): ) -_RAD2DEG_DOCSTRING = """ -Convert angles from radians to degrees. +_RAD2DEG_DOCSTRING = r""" +Convert angles from degrees to radians for each element :math:`x_i` for input +array `x`. For full documentation refer to :obj:`numpy.rad2deg`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Angle in radians. + Input array, expected to have a real-valued floating-point data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -1833,8 +1846,9 @@ def logsumexp(x, /, *, axis=None, dtype=None, keepdims=False, out=None): Returns ------- out : dpnp.ndarray - The corresponding angle in degrees. The data type of the returned array is - determined by the Type Promotion Rules. + An array containing the element-wise angle in degrees. + The data type of the returned array is determined by the Type Promotion + Rules. Limitations ----------- @@ -1850,7 +1864,9 @@ def logsumexp(x, /, *, axis=None, dtype=None, keepdims=False, out=None): Notes ----- -dpnp.rad2deg(x) is ``180 * x / pi``. +The mathematical definition is + +.. math:: \operatorname{rad2deg}(x) = \frac{180 * x}{\pi} Examples -------- @@ -1869,15 +1885,16 @@ def logsumexp(x, /, *, axis=None, dtype=None, keepdims=False, out=None): ) -_RADIANS_DOCSTRING = """ -Convert angles from degrees to radians. +_RADIANS_DOCSTRING = r""" +Convert angles from degrees to radians for each element :math:`x_i` for input +array `x`. For full documentation refer to :obj:`numpy.radians`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array in degrees. + Input array, expected to have a real-valued floating-point data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -1891,8 +1908,9 @@ def logsumexp(x, /, *, axis=None, dtype=None, keepdims=False, out=None): Returns ------- out : dpnp.ndarray - The corresponding radian values. The data type of the returned array is - determined by the Type Promotion Rules. + An array containing the element-wise angle in radians. + The data type of the returned array is determined by the Type Promotion + Rules. Limitations ----------- @@ -1904,6 +1922,12 @@ def logsumexp(x, /, *, axis=None, dtype=None, keepdims=False, out=None): -------- :obj:`dpnp.deg2rad` : Equivalent function. +Notes +----- +The mathematical definition is + +.. math:: \operatorname{radians}(x) = \frac{x * \pi}{180} + Examples -------- >>> import dpnp as np From 80b90c3f13d5a9f3d80330dfedf4345145f1f6db Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Wed, 2 Apr 2025 22:05:57 +0200 Subject: [PATCH 18/32] Update docstring of `exp`, `exp2`, and `expm1` functions to use math where applicable --- dpnp/dpnp_iface_trigonometric.py | 57 ++++++++++++++++++-------------- 1 file changed, 32 insertions(+), 25 deletions(-) diff --git a/dpnp/dpnp_iface_trigonometric.py b/dpnp/dpnp_iface_trigonometric.py index 6178886cdbfe..ca3e800c1f49 100644 --- a/dpnp/dpnp_iface_trigonometric.py +++ b/dpnp/dpnp_iface_trigonometric.py @@ -1092,14 +1092,14 @@ def cumlogsumexp( _EXP_DOCSTRING = """ -Computes the exponent for each element `x_i` of input array `x`. +Computes the exponential for each element :math:`x_i` of input array `x`. For full documentation refer to :obj:`numpy.exp`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + Input array, expected to have a floating-point data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -1113,9 +1113,9 @@ def cumlogsumexp( Returns ------- out : dpnp.ndarray - An array containing the element-wise exponent of `x`. - The data type of the returned array is determined by - the Type Promotion Rules. + An array containing the element-wise exponential of `x`. + The data type of the returned array is determined by the Type Promotion + Rules. Limitations ----------- @@ -1125,8 +1125,8 @@ def cumlogsumexp( See Also -------- -:obj:`dpnp.expm1` : Calculate ``exp(x) - 1`` for all elements in the array. -:obj:`dpnp.exp2` : Calculate `2**x` for all elements in the array. +:obj:`dpnp.expm1` : Calculate :math:`e^x - 1`, element-wise. +:obj:`dpnp.exp2` : Calculate :math:`2^x`, element-wise. Examples -------- @@ -1148,7 +1148,8 @@ def cumlogsumexp( _EXP2_DOCSTRING = """ -Computes the base-2 exponent for each element `x_i` for input array `x`. +Computes the base-2 exponential for each element :math:`x_i` for input array +`x`. For full documentation refer to :obj:`numpy.exp2`. @@ -1169,9 +1170,9 @@ def cumlogsumexp( Returns ------- out : dpnp.ndarray - An array containing the element-wise base-2 exponents. - The data type of the returned array is determined by - the Type Promotion Rules. + An array containing the element-wise base-2 exponentials. + The data type of the returned array is determined by the Type Promotion + Rules. Limitations ----------- @@ -1181,9 +1182,10 @@ def cumlogsumexp( See Also -------- -:obj:`dpnp.exp` : Calculate exponent for all elements in the array. -:obj:`dpnp.expm1` : ``exp(x) - 1``, the inverse of :obj:`dpnp.log1p`. -:obj:`dpnp.power` : First array elements raised to powers from second array, element-wise. +:obj:`dpnp.exp` : Calculate :math:`e^x`, element-wise. +:obj:`dpnp.expm1` : Calculate :math:`e^x - 1`, element-wise. +:obj:`dpnp.power` : Exponentiation by raising the first array to the power of + the second array, element-wise. Examples -------- @@ -1204,17 +1206,16 @@ def cumlogsumexp( ) -_EXPM1_DOCSTRING = """ -Computes the exponent minus 1 for each element `x_i` of input array `x`. - -This function calculates `exp(x) - 1.0` more accurately for small values of `x`. +_EXPM1_DOCSTRING = r""" +Computes the exponential minus 1 for each element :math:`x_i` of input array +`x`. For full documentation refer to :obj:`numpy.expm1`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + Input array, expected to have a floating-point data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -1228,9 +1229,9 @@ def cumlogsumexp( Returns ------- out : dpnp.ndarray - An array containing the element-wise `exp(x) - 1` results. - The data type of the returned array is determined by the Type - Promotion Rules. + An array containing containing the evaluated result for each element in `x`. + The data type of the returned array is determined by the Type Promotion + Rules. Limitations ----------- @@ -1240,9 +1241,15 @@ def cumlogsumexp( See Also -------- -:obj:`dpnp.exp` : Calculate exponents for all elements in the array. -:obj:`dpnp.exp2` : Calculate `2**x` for all elements in the array. -:obj:`dpnp.log1p` : Calculate ``log(1 + x)``, the inverse of :obj:`dpnp.expm1`. +:obj:`dpnp.exp` : Calculate :math:`e^x`, element-wise. +:obj:`dpnp.exp2` : Calculate :math:`2^x`, element-wise. +:obj:`dpnp.log1p` : Calculate :math:`\log(1 + x)`, element-wise, + the inverse of :obj:`dpnp.expm1`. + +Notes +----- +This function provides greater precision than :math:`e^x - 1` for small values +of `x`. Examples -------- From bac9deba21b20cd6120ddb5a9f8d5a38f1f93935 Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Thu, 3 Apr 2025 11:58:29 +0200 Subject: [PATCH 19/32] Update docstring of `hypot` function to use math where applicable --- dpnp/dpnp_iface_trigonometric.py | 30 +++++++++++++++++++----------- 1 file changed, 19 insertions(+), 11 deletions(-) diff --git a/dpnp/dpnp_iface_trigonometric.py b/dpnp/dpnp_iface_trigonometric.py index ca3e800c1f49..d4a23524ff42 100644 --- a/dpnp/dpnp_iface_trigonometric.py +++ b/dpnp/dpnp_iface_trigonometric.py @@ -1276,9 +1276,10 @@ def cumlogsumexp( ) -_HYPOT_DOCSTRING = """ -Calculates the hypotenuse for a right triangle with "legs" `x1_i` and `x2_i` of -input arrays `x1` and `x2`. +_HYPOT_DOCSTRING = r""" +Computes the square root of the sum of squares for each element :math:`x1_i` of +the input array `x1` with the respective element :math:`x2_i` of the input +array `x2`. For full documentation refer to :obj:`numpy.hypot`. @@ -1286,12 +1287,9 @@ def cumlogsumexp( ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} First input array, expected to have a real-valued floating-point data type. - Both inputs `x1` and `x2` can not be scalars at the same time. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have a real-valued floating-point data type. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also expected to have a real-valued floating-point data + type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -1305,8 +1303,8 @@ def cumlogsumexp( Returns ------- out : dpnp.ndarray - An array containing the element-wise hypotenuse. The data type - of the returned array is determined by the Type Promotion Rules. + An array containing the element-wise hypotenuse. The data type of the + returned array is determined by the Type Promotion Rules. Limitations ----------- @@ -1316,7 +1314,17 @@ def cumlogsumexp( See Also -------- -:obj:`dpnp.reduce_hypot` : The square root of the sum of squares of elements in the input array. +:obj:`dpnp.reduce_hypot` : The square root of the sum of squares of elements + in the input array. + +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + +This function is equivalent to :math:`\sqrt{x1^2 + x2^2}`, element-wise. Examples -------- From 0e35d6404721741a088d4c3510e4f18c3976fc39 Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Thu, 3 Apr 2025 12:34:57 +0200 Subject: [PATCH 20/32] Update docstring of `log`, `log10`, `log1p`, and `log2` functions to use math where applicable --- dpnp/dpnp_iface_trigonometric.py | 148 ++++++++++++++++++++++--------- 1 file changed, 107 insertions(+), 41 deletions(-) diff --git a/dpnp/dpnp_iface_trigonometric.py b/dpnp/dpnp_iface_trigonometric.py index d4a23524ff42..13133aa36f28 100644 --- a/dpnp/dpnp_iface_trigonometric.py +++ b/dpnp/dpnp_iface_trigonometric.py @@ -1355,15 +1355,15 @@ def cumlogsumexp( ) -_LOG_DOCSTRING = """ -Computes the natural logarithm for each element `x_i` of input array `x`. +_LOG_DOCSTRING = r""" +Computes the natural logarithm for each element :math:`x_i` of input array `x`. For full documentation refer to :obj:`numpy.log`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + Input array, expected to have a floating-point data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -1377,9 +1377,8 @@ def cumlogsumexp( Returns ------- out : dpnp.ndarray - An array containing the element-wise natural logarithm values. - The data type of the returned array is determined by the Type - Promotion Rules. + An array containing the element-wise natural logarithm values. The data + type of the returned array is determined by the Type Promotion Rules. Limitations ----------- @@ -1389,11 +1388,27 @@ def cumlogsumexp( See Also -------- -:obj:`dpnp.log10` : Return the base 10 logarithm of the input array, - element-wise. -:obj:`dpnp.log2` : Base-2 logarithm of x. -:obj:`dpnp.log1p` : Return the natural logarithm of one plus - the input array, element-wise. +:obj:`dpnp.log10` : Calculate :math:`\log_{10}(x)`, element-wise. +:obj:`dpnp.log2` : Calculate :math:`\log_2(x)`, element-wise. +:obj:`dpnp.log1p` : Calculate :math:`\log(1 + x)`, element-wise. + +Notes +----- +:obj:`dpnp.log` is a multivalued function: for each `x` there are infinitely +many numbers `z` such that :math:`e^z = x`. The convention is to return the `z` +whose the imaginary part lies in the interval :math:`[-\pi, \pi]`. + +For real-valued floating-point input data types, :obj:`dpnp.log` always returns +real output. For each value that cannot be expressed as a real number or +nfinity, it yields ``NaN``. + +For complex floating-point input data types, :obj:`dpnp.log` is a complex +analytic function that has, by convention, the branch cuts +:math:`(-\infty, 0)` and is continuous from above on it. + +In the cases where the input has a negative real part and a very small negative +complex part (approaching 0), the result is so close to :math:`-\pi` that it +evaluates to exactly :math:`-\pi`. Examples -------- @@ -1414,15 +1429,15 @@ def cumlogsumexp( ) -_LOG10_DOCSTRING = """ -Computes the base-10 logarithm for each element `x_i` of input array `x`. +_LOG10_DOCSTRING = r""" +Computes the base-10 logarithm for each element :math:`x_i` of input array `x`. For full documentation refer to :obj:`numpy.log10`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + Input array, expected to have a floating-point data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -1436,9 +1451,8 @@ def cumlogsumexp( Returns ------- out : dpnp.ndarray - An array containing the element-wise base-10 logarithm of `x`. - The data type of the returned array is determined by the - Type Promotion Rules. + An array containing the element-wise base-10 logarithm of `x`. The data + type of the returned array is determined by the Type Promotion Rules. Limitations ----------- @@ -1448,9 +1462,27 @@ def cumlogsumexp( See Also -------- -:obj:`dpnp.log` : Natural logarithm, element-wise. -:obj:`dpnp.log2` : Return the base-2 logarithm of the input array, element-wise. -:obj:`dpnp.log1p` : Return the natural logarithm of one plus the input array, element-wise. +:obj:`dpnp.log` : Calculate :math:`\log(x)`, element-wise. +:obj:`dpnp.log2` : Calculate :math:`\log_2(x)`, element-wise. +:obj:`dpnp.log1p` : Calculate :math:`\log(1 + x)`, element-wise. + +Notes +----- +:obj:`dpnp.log10` is a multivalued function: for each `x` there are infinitely +many numbers `z` such that :math:`10^z = x`. The convention is to return the `z` +whose the imaginary part lies in the interval :math:`[-\pi, \pi]`. + +For real-valued floating-point input data types, :obj:`dpnp.log10` always +returns real output. For each value that cannot be expressed as a real number +or nfinity, it yields ``NaN``. + +For complex floating-point input data types, :obj:`dpnp.log10` is a complex +analytic function that has, by convention, the branch cuts +:math:`(-\infty, 0)` and is continuous from above on it. + +In the cases where the input has a negative real part and a very small negative +complex part (approaching 0), the result is so close to :math:`-\pi` that it +evaluates to exactly :math:`-\pi`. Examples -------- @@ -1474,18 +1506,16 @@ def cumlogsumexp( ) -_LOG1P_DOCSTRING = """ -Computes the natural logarithm of (1 + `x`) for each element `x_i` of input -array `x`. - -This function calculates `log(1 + x)` more accurately for small values of `x`. +_LOG1P_DOCSTRING = r""" +Computes the natural logarithm of (1 + `x`) for each element :math:`x_i` of +input array `x`. For full documentation refer to :obj:`numpy.log1p`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + Input array, expected to have a floating-point data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -1499,8 +1529,8 @@ def cumlogsumexp( Returns ------- out : dpnp.ndarray - An array containing the element-wise `log(1 + x)` results. The data type - of the returned array is determined by the Type Promotion Rules. + An array containing the element-wise :math:`\log(1 + x)` results. The data + type of the returned array is determined by the Type Promotion Rules. Limitations ----------- @@ -1510,10 +1540,29 @@ def cumlogsumexp( See Also -------- -:obj:`dpnp.expm1` : ``exp(x) - 1``, the inverse of :obj:`dpnp.log1p`. -:obj:`dpnp.log` : Natural logarithm, element-wise. -:obj:`dpnp.log10` : Return the base 10 logarithm of the input array, element-wise. -:obj:`dpnp.log2` : Return the base-2 logarithm of the input array, element-wise. +:obj:`dpnp.expm1` : Calculate :math:`e^x - 1`, element-wise, + the inverse of :obj:`dpnp.log1p`. +:obj:`dpnp.log` : Calculate :math:`\log(x)`, element-wise. +:obj:`dpnp.log10` : Calculate :math:`\log_{10}(x)`, element-wise. +:obj:`dpnp.log2` : Calculate :math:`\log_2(x)`, element-wise. + +Notes +----- +For real-valued floating-point input data types, :obj:`dpnp.log1p` provides +greater precision than :math:`\log(1 + x)` for `x` so small that +:math:`1 + x == 1`. + +:obj:`dpnp.log1p` is a multivalued function: for each `x` there are infinitely +many numbers `z` such that :math:`e^z = 1 + x`. The convention is to return the +`z` whose the imaginary part lies in the interval :math:`[-\pi, \pi]`. + +For real-valued floating-point input data types, :obj:`dpnp.log1p` always +returns real output. For each value that cannot be expressed as a real number +or nfinity, it yields ``NaN``. + +For complex floating-point input data types, :obj:`dpnp.log1p` is a complex +analytic function that has, by convention, the branch cuts +:math:`(-\infty, 0)` and is continuous from above on it. Examples -------- @@ -1540,15 +1589,15 @@ def cumlogsumexp( ) -_LOG2_DOCSTRING = """ -Computes the base-2 logarithm for each element `x_i` of input array `x`. +_LOG2_DOCSTRING = r""" +Computes the base-2 logarithm for each element :math:`x_i` of input array `x`. For full documentation refer to :obj:`numpy.log2`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + Input array, expected to have a floating-point data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -1562,9 +1611,8 @@ def cumlogsumexp( Returns ------- out : dpnp.ndarray - An array containing the element-wise base-2 logarithm of `x`. - The data type of the returned array is determined by the - Type Promotion Rules. + An array containing the element-wise base-2 logarithm of `x`. The data type + of the returned array is determined by the Type Promotion Rules. Limitations ----------- @@ -1574,9 +1622,27 @@ def cumlogsumexp( See Also -------- -:obj:`dpnp.log` : Natural logarithm, element-wise. -:obj:`dpnp.log10` : Return the base 10 logarithm of the input array, element-wise. -:obj:`dpnp.log1p` : Return the natural logarithm of one plus the input array, element-wise. +:obj:`dpnp.log` : Calculate :math:`\log(x)`, element-wise. +:obj:`dpnp.log10` : Calculate :math:`\log_{10}(x)`, element-wise. +:obj:`dpnp.log1p` : Calculate :math:`\log(1 + x)`, element-wise. + +Notes +----- +:obj:`dpnp.log2` is a multivalued function: for each `x` there are infinitely +many numbers `z` such that :math:`2^z = x`. The convention is to return the `z` +whose the imaginary part lies in the interval :math:`[-\pi, \pi]`. + +For real-valued floating-point input data types, :obj:`dpnp.log2` always +returns real output. For each value that cannot be expressed as a real number +or nfinity, it yields ``NaN``. + +For complex floating-point input data types, :obj:`dpnp.log2` is a complex +analytic function that has, by convention, the branch cuts +:math:`(-\infty, 0)` and is continuous from above on it. + +In the cases where the input has a negative real part and a very small negative +complex part (approaching 0), the result is so close to :math:`-\pi` that it +evaluates to exactly :math:`-\pi`. Examples -------- From 75dd5746e1a05cfbc48cdd55c8891b52a74cf4b6 Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Thu, 3 Apr 2025 14:08:35 +0200 Subject: [PATCH 21/32] Update docstring of `logaddexp`, `logaddexp2` and `cumlogsumexp` functions to use math where applicable --- dpnp/dpnp_iface_trigonometric.py | 125 +++++++++++++++++-------------- 1 file changed, 68 insertions(+), 57 deletions(-) diff --git a/dpnp/dpnp_iface_trigonometric.py b/dpnp/dpnp_iface_trigonometric.py index 13133aa36f28..1724e29ac555 100644 --- a/dpnp/dpnp_iface_trigonometric.py +++ b/dpnp/dpnp_iface_trigonometric.py @@ -878,7 +878,8 @@ def cumlogsumexp( Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have a boolean or real-valued data type. + Input array, expected to have a boolean or real-valued floating-point + data type. axis : {None, int}, optional Axis or axes along which values must be computed. If a tuple of unique integers, values are computed over multiple axes. If ``None``, the @@ -924,15 +925,15 @@ def cumlogsumexp( has the data type as described in the `dtype` parameter description above. - Note - ---- - This function is equivalent of `numpy.logaddexp.accumulate`. - See Also -------- :obj:`dpnp.logsumexp` : Logarithm of the sum of elements of the inputs, element-wise. + Note + ---- + This function is equivalent of `numpy.logaddexp.accumulate`. + Examples -------- >>> import dpnp as np @@ -1667,13 +1668,10 @@ def cumlogsumexp( ) -_LOGADDEXP_DOCSTRING = """ -Calculates the natural logarithm of the sum of exponents for each element `x1_i` -of the input array `x1` with the respective element `x2_i` of the input -array `x2`. - -This function calculates `log(exp(x1) + exp(x2))` more accurately for small -values of `x`. +_LOGADDEXP_DOCSTRING = r""" +Calculates the natural logarithm of the sum of exponentiations +:math:`\log(e^{x1} + e^{x2})` for each element :math:`x1_i` of the input array +`x1` with the respective element :math:`x2_i` of the input array `x2`. For full documentation refer to :obj:`numpy.logaddexp`. @@ -1682,13 +1680,9 @@ def cumlogsumexp( x1 : {dpnp.ndarray, usm_ndarray, scalar} First input array, expected to have a real-valued floating-point data type. - Both inputs `x1` and `x2` can not be scalars at the same time. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have a real-valued - floating-point data type. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also expected to have a real-valued floating-point data + type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -1702,8 +1696,8 @@ def cumlogsumexp( Returns ------- out : dpnp.ndarray - An array containing the element-wise results. The data type - of the returned array is determined by the Type Promotion Rules. + An array containing the element-wise results. The data type of the returned + array is determined by the Type Promotion Rules. Limitations ----------- @@ -1713,12 +1707,23 @@ def cumlogsumexp( See Also -------- -:obj:`dpnp.log` : Natural logarithm, element-wise. -:obj:`dpnp.exp` : Exponential, element-wise. -:obj:`dpnp.logaddexp2`: Logarithm of the sum of exponentiation of inputs in - base-2, element-wise. -:obj:`dpnp.logsumexp` : Logarithm of the sum of exponents of elements in the - input array. +:obj:`dpnp.log` : Calculate :math:`\log(x)`, element-wise. +:obj:`dpnp.exp` : Calculate :math:`e^x`, element-wise. +:obj:`dpnp.logaddexp2`: Calculate :math:`\log_2(2^{x1} + 2^{x2})`, element-wise. +:obj:`dpnp.logsumexp` : Logarithm of the sum of exponentials of elements in the + input array. + +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + +This function is useful in statistics where the calculated probabilities of +events may be so small as to exceed the range of normal floating-point numbers. +In such cases the natural logarithm of the calculated probability is stored. +This function allows adding probabilities stored in such a fashion. Examples -------- @@ -1741,16 +1746,10 @@ def cumlogsumexp( ) -_LOGADDEXP2_DOCSTRING = """ -Calculates the logarithm of the sum of exponents in base-2 for each element -`x1_i` of the input array `x1` with the respective element `x2_i` of the input -array `x2`. - -This function calculates `log2(2**x1 + 2**x2)`. It 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 the base-2 -logarithm of the calculated probability can be used instead. This function -allows adding probabilities stored in such a fashion. +_LOGADDEXP2_DOCSTRING = r""" +Calculates the base-2 logarithm of the sum of exponentiations +:math:`\log_2(2^{x1} + 2^{x2})` for each element :math:`x1_i` of the input +array `x1` with the respective element :math:`x2_i` of the input array `x2`. For full documentation refer to :obj:`numpy.logaddexp2`. @@ -1759,13 +1758,9 @@ def cumlogsumexp( x1 : {dpnp.ndarray, usm_ndarray, scalar} First input array, expected to have a real-valued floating-point data type. - Both inputs `x1` and `x2` can not be scalars at the same time. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have a real-valued - floating-point data type. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also expected to have a real-valued floating-point data + type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -1790,9 +1785,22 @@ def cumlogsumexp( See Also -------- -:obj:`dpnp.logaddexp`: Natural logarithm of the sum of exponentiation of - inputs, element-wise. -:obj:`dpnp.logsumexp` : Logarithm of the sum of exponentiation of the inputs. +:obj:`dpnp.logaddexp`: Calculate :math:`\log(e^{x1} + e^{x2})`, element-wise. +:obj:`dpnp.logsumexp` : Logarithm of the sum of exponentials of elements in the + input array. + +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + +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 the base-2 logarithm of the calculated probability can +be used instead. This function allows adding probabilities stored in such a +fashion. Examples -------- @@ -1816,14 +1824,15 @@ def cumlogsumexp( def logsumexp(x, /, *, axis=None, dtype=None, keepdims=False, out=None): - """ - Calculates the logarithm of the sum of exponents of elements in + r""" + Calculates the natural logarithm of the sum of exponentials of elements in the input array. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have a real-valued floating-point data type. + Input array, expected to have a boolean or real-valued floating-point + data type. axis : {None, int or tuple of ints}, optional Axis or axes along which values must be computed. If a tuple of unique integers, values are computed over multiple axes. If ``None``, the @@ -1868,19 +1877,21 @@ def logsumexp(x, /, *, axis=None, dtype=None, keepdims=False, out=None): has the data type as described in the `dtype` parameter description above. + See Also + -------- + :obj:`dpnp.log` : Calculate :math:`\log(x)`, element-wise. + :obj:`dpnp.exp` : Calculate :math:`e^x`, element-wise. + :obj:`dpnp.logaddexp`: Calculate :math:`\log(e^{x1} + e^{x2})`, + element-wise. + :obj:`dpnp.logaddexp2`: Calculate :math:`\log_2(2^{x1} + 2^{x2})`, + element-wise. + :obj:`dpnp.cumlogsumexp` : Cumulative the natural logarithm of the sum of + elements in the input array. + Note ---- This function is equivalent of `numpy.logaddexp.reduce`. - See Also - -------- - :obj:`dpnp.log` : Natural logarithm, element-wise. - :obj:`dpnp.exp` : Exponential, element-wise. - :obj:`dpnp.logaddexp` : Logarithm of the sum of exponents of - the inputs, element-wise. - :obj:`dpnp.logaddexp2` : Logarithm of the sum of exponents of - the inputs in base-2, element-wise. - Examples -------- >>> import dpnp as np From fc27d3aaa111cff1605cfcfc1be6663ec53553c7 Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Thu, 3 Apr 2025 15:59:29 +0200 Subject: [PATCH 22/32] Update docstring of `reciprocal`, `rsqrt` and `sqrt` functions to use math where applicable --- dpnp/dpnp_iface_trigonometric.py | 83 +++++++++++++++++++++----------- 1 file changed, 54 insertions(+), 29 deletions(-) diff --git a/dpnp/dpnp_iface_trigonometric.py b/dpnp/dpnp_iface_trigonometric.py index 1724e29ac555..b73f77f87e70 100644 --- a/dpnp/dpnp_iface_trigonometric.py +++ b/dpnp/dpnp_iface_trigonometric.py @@ -694,8 +694,8 @@ def _get_accumulation_res_dt(a, dtype): arctanh = atanh # arctanh is an alias for atanh -_CBRT_DOCSTRING = """ -Computes positive cube-root for each element :math:`x_i` for input array `x`. +_CBRT_DOCSTRING = r""" +Computes the cube-root for each element :math:`x_i` for input array `x`. For full documentation refer to :obj:`numpy.cbrt`. @@ -716,9 +716,8 @@ def _get_accumulation_res_dt(a, dtype): Returns ------- out : dpnp.ndarray - An array containing the element-wise positive cube-root. - The data type of the returned array is determined by the Type Promotion - Rules. + An array containing the element-wise cube-root. The data type of the + returned array is determined by the Type Promotion Rules. Limitations ----------- @@ -728,7 +727,11 @@ def _get_accumulation_res_dt(a, dtype): See Also -------- -:obj:`dpnp.sqrt` : Return the positive square-root of an array, element-wise. +:obj:`dpnp.sqrt` : Calculate :math:`\sqrt{x}`, element-wise. + +Notes +----- +This function is equivalent to :math:`\sqrt[3]{x}`, element-wise. Examples -------- @@ -2047,15 +2050,15 @@ def logsumexp(x, /, *, axis=None, dtype=None, keepdims=False, out=None): ) -_RECIPROCAL_DOCSTRING = """ -Computes the reciprocal square-root for each element `x_i` for input array `x`. +_RECIPROCAL_DOCSTRING = r""" +Computes the reciprocal for each element :math:`x_i` for input array `x`. For full documentation refer to :obj:`numpy.reciprocal`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have a real-valued floating-point data type. + Input array, expected to have a floating-point data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -2069,9 +2072,8 @@ def logsumexp(x, /, *, axis=None, dtype=None, keepdims=False, out=None): Returns ------- out : dpnp.ndarray - An array containing the element-wise reciprocals. - The returned array has a floating-point data type determined - by the Type Promotion Rules. + An array containing the element-wise reciprocals. The returned array has + a floating-point data type determined by the Type Promotion Rules. Limitations ----------- @@ -2081,7 +2083,11 @@ def logsumexp(x, /, *, axis=None, dtype=None, keepdims=False, out=None): See Also -------- -:obj:`dpnp.rsqrt` : Return the reciprocal square-root of an array, element-wise. +:obj:`dpnp.rsqrt` : Calculate :math:`\frac{1}{\sqrt{x}}`, element-wise. + +Notes +----- +This function is equivalent to :math:`\frac{1}{x}`, element-wise. Examples -------- @@ -2185,8 +2191,9 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): ) -_RSQRT_DOCSTRING = """ -Computes the reciprocal square-root for each element `x_i` for input array `x`. +_RSQRT_DOCSTRING = r""" +Computes the reciprocal square-root for each element :math:`x_i` for input +array `x`. Parameters ---------- @@ -2204,7 +2211,7 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): Returns ------- out : dpnp.ndarray - An array containing the element-wise reciprocal square-root. + An array containing the element-wise reciprocal square-roots. The returned array has a floating-point data type determined by the Type Promotion Rules. @@ -2216,8 +2223,12 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): See Also -------- -:obj:`dpnp.sqrt` : Return the positive square-root of an array, element-wise. -:obj:`dpnp.reciprocal` : Return the reciprocal of an array, element-wise. +:obj:`dpnp.sqrt` : Calculate :math:`\sqrt{x}`, element-wise. +:obj:`dpnp.reciprocal` : Calculate :math:`\frac{1}{x}`, element-wise. + +Notes +----- +This function is equivalent to :math:`\frac{1}{\sqrt{x}}`, element-wise. Examples -------- @@ -2350,15 +2361,16 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): ) -_SQRT_DOCSTRING = """ -Computes the positive square-root for each element `x_i` of input array `x`. +_SQRT_DOCSTRING = r""" +Computes the principal square-root for each element :math:`x_i` of input array +`x`. For full documentation refer to :obj:`numpy.sqrt`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array. + Input array, expected to have a floating-point data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -2372,9 +2384,8 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): Returns ------- out : dpnp.ndarray - An array containing the element-wise positive square-roots of `x`. The - data type of the returned array is determined by the Type Promotion - Rules. + An array containing the element-wise principal square-roots of `x`. The + data type of the returned array is determined by the Type Promotion Rules. Limitations ----------- @@ -2384,8 +2395,23 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): See Also -------- -:obj:`dpnp.cbrt` : Return the cube-root of an array, element-wise. -:obj:`dpnp.rsqrt` : Return the reciprocal square-root of an array, element-wise. +:obj:`dpnp.cbrt` : Calculate :math:`\sqrt[3]{x}`, element-wise. +:obj:`dpnp.rsqrt` : Calculate :math:`\frac{1}{\sqrt{x}}`, element-wise. + +Notes +----- +This function is equivalent to :math:`\sqrt{x}`, element-wise. + +By convention, the branch cut of the square root is the negative real axis +:math:`(-\infty, 0)`. + +The square root is a continuous function from above the branch cut, taking into +account the sign of the imaginary component. + +Accordingly, for complex arguments, the function returns the square root in the +range of the right half-plane, including the imaginary axis (i.e., the plane +defined by :math:`[0, +\infty)` along the real axis and +:math:`(-\infty, +\infty)` along the imaginary axis). Examples -------- @@ -2410,7 +2436,7 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): ) -_SQUARE_DOCSTRING = """ +_SQUARE_DOCSTRING = r""" Squares each element `x_i` of input array `x`. For full documentation refer to :obj:`numpy.square`. @@ -2445,8 +2471,7 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): -------- :obj:`dpnp..linalg.matrix_power` : Raise a square matrix to the (integer) power `n`. -:obj:`dpnp.sqrt` : Return the positive square-root of an array, - element-wise. +:obj:`dpnp.sqrt` : Calculate :math:`\sqrt{x}`, element-wise. :obj:`dpnp.power` : First array elements raised to powers from second array, element-wise. From f7e2d20ddf4eb4cdfaed035b30ccf7c75853ab99 Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Thu, 3 Apr 2025 16:20:18 +0200 Subject: [PATCH 23/32] Update docstring of `reduce_hypot` function to use math where applicable --- dpnp/dpnp_iface_trigonometric.py | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/dpnp/dpnp_iface_trigonometric.py b/dpnp/dpnp_iface_trigonometric.py index b73f77f87e70..fff6782b599f 100644 --- a/dpnp/dpnp_iface_trigonometric.py +++ b/dpnp/dpnp_iface_trigonometric.py @@ -2107,14 +2107,15 @@ def logsumexp(x, /, *, axis=None, dtype=None, keepdims=False, out=None): def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): - """ + r""" Calculates the square root of the sum of squares of elements in the input array. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have a real-valued floating-point data type. + Input array, expected to have a boolean or real-valued floating-point + data type. axis : {None, int or tuple of ints}, optional Axis or axes along which values must be computed. If a tuple of unique integers, values are computed over multiple axes. If ``None``, the @@ -2159,15 +2160,14 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): has the data type as described in the `dtype` parameter description above. + See Also + -------- + :obj:`dpnp.hypot` : Calculates :math:`\sqrt{x1^2 + x2^2}`, element-wise. + Note ---- This function is equivalent of `numpy.hypot.reduce`. - See Also - -------- - :obj:`dpnp.hypot` : Given the "legs" of a right triangle, return its - hypotenuse. - Examples -------- >>> import dpnp as np From 8c3bccbd80c862922850e8dd6d78ecf32ca6f4d1 Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Thu, 3 Apr 2025 18:07:01 +0200 Subject: [PATCH 24/32] Update docstring of `sin` and `sinh` functions to use math where applicable --- dpnp/dpnp_iface_trigonometric.py | 30 +++++++++++++++++------------- 1 file changed, 17 insertions(+), 13 deletions(-) diff --git a/dpnp/dpnp_iface_trigonometric.py b/dpnp/dpnp_iface_trigonometric.py index fff6782b599f..756d4348cc44 100644 --- a/dpnp/dpnp_iface_trigonometric.py +++ b/dpnp/dpnp_iface_trigonometric.py @@ -753,7 +753,7 @@ def _get_accumulation_res_dt(a, dtype): _COS_DOCSTRING = """ -Computes cosine for each element :math:`x_i` for input array `x`. +Computes the cosine for each element :math:`x_i` for input array `x`. For full documentation refer to :obj:`numpy.cos`. @@ -810,7 +810,7 @@ def _get_accumulation_res_dt(a, dtype): _COSH_DOCSTRING = r""" -Computes hyperbolic cosine for each element :math:`x_i` for input array `x`. +Computes the hyperbolic cosine for each element :math:`x_i` for input array `x`. The mathematical definition of the hyperbolic cosine is @@ -2248,14 +2248,14 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): _SIN_DOCSTRING = """ -Computes sine for each element `x_i` of input array `x`. +Computes the sine for each element :math:`x_i` of input array `x`. For full documentation refer to :obj:`numpy.sin`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + Input array, expected to have a floating-point data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -2269,8 +2269,8 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): Returns ------- out : dpnp.ndarray - An array containing the element-wise sine. The data type of the - returned array is determined by the Type Promotion Rules. + An array containing the element-wise sine. The data type of the returned + array is determined by the Type Promotion Rules. Limitations ----------- @@ -2280,7 +2280,7 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): See Also -------- -:obj:`dpnp.arcsin` : Trigonometric inverse sine, element-wise. +:obj:`dpnp.asin` : Trigonometric inverse sine, element-wise. :obj:`dpnp.cos` : Trigonometric cosine, element-wise. :obj:`dpnp.tan` : Trigonometric tangent, element-wise. :obj:`dpnp.sinh` : Hyperbolic sine, element-wise. @@ -2304,15 +2304,19 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): ) -_SINH_DOCSTRING = """ -Computes hyperbolic sine for each element `x_i` for input array `x`. +_SINH_DOCSTRING = r""" +Computes the hyperbolic sine for each element :math:`x_i` for input array `x`. + +The mathematical definition of the hyperbolic sine is + +.. math:: \operatorname{sinh}(x) = \frac{e^x - e^{-x}}{2} For full documentation refer to :obj:`numpy.sinh`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + Input array, expected to have a floating-point data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -2326,8 +2330,8 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): Returns ------- out : dpnp.ndarray - An array containing the element-wise hyperbolic sine. The data type - of the returned array is determined by the Type Promotion Rules. + An array containing the element-wise hyperbolic sine. The data type of the + returned array is determined by the Type Promotion Rules. Limitations ----------- @@ -2337,7 +2341,7 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): See Also -------- -:obj:`dpnp.arcsinh` : Hyperbolic inverse sine, element-wise. +:obj:`dpnp.asinh` : Hyperbolic inverse sine, element-wise. :obj:`dpnp.cosh` : Hyperbolic cosine, element-wise. :obj:`dpnp.tanh` : Hyperbolic tangent, element-wise. :obj:`dpnp.sin` : Trigonometric sine, element-wise. From 89d93e68860c24e517dbdeb3adc1d5cbd43d4de8 Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Thu, 3 Apr 2025 19:01:50 +0200 Subject: [PATCH 25/32] Update `square`, `tan`, `tanh` and `unwrap` functions to use math where applicable --- dpnp/dpnp_iface_trigonometric.py | 72 ++++++++++++++++++-------------- 1 file changed, 41 insertions(+), 31 deletions(-) diff --git a/dpnp/dpnp_iface_trigonometric.py b/dpnp/dpnp_iface_trigonometric.py index 756d4348cc44..b0474e4c9222 100644 --- a/dpnp/dpnp_iface_trigonometric.py +++ b/dpnp/dpnp_iface_trigonometric.py @@ -774,8 +774,8 @@ def _get_accumulation_res_dt(a, dtype): Returns ------- out : dpnp.ndarray - An array containing the element-wise cosine. The data type of the returned - array is determined by the Type Promotion Rules. + An array containing the element-wise cosine, in radians. The data type of + the returned array is determined by the Type Promotion Rules. Limitations ----------- @@ -2269,8 +2269,8 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): Returns ------- out : dpnp.ndarray - An array containing the element-wise sine. The data type of the returned - array is determined by the Type Promotion Rules. + An array containing the element-wise sine, in radians. The data type of the + returned array is determined by the Type Promotion Rules. Limitations ----------- @@ -2441,14 +2441,14 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): _SQUARE_DOCSTRING = r""" -Squares each element `x_i` of input array `x`. +Squares each element :math:`x_i` of input array `x`. For full documentation refer to :obj:`numpy.square`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array. + Input array, expected to have a boolean or numeric data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -2462,8 +2462,8 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): Returns ------- out : dpnp.ndarray - An array containing the element-wise squares of `x`. The data type of - the returned array is determined by the Type Promotion Rules. + An array containing the element-wise squares of `x`. The data type of the + returned array is determined by the Type Promotion Rules. Limitations ----------- @@ -2473,11 +2473,11 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): See Also -------- -:obj:`dpnp..linalg.matrix_power` : Raise a square matrix - to the (integer) power `n`. +:obj:`dpnp..linalg.matrix_power` : Raise a square matrix to the (integer) + power `n`. :obj:`dpnp.sqrt` : Calculate :math:`\sqrt{x}`, element-wise. -:obj:`dpnp.power` : First array elements raised to powers - from second array, element-wise. +:obj:`dpnp.power` : Exponentiation by raising the first array to the power of + the second array, element-wise. Examples -------- @@ -2499,14 +2499,14 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): _TAN_DOCSTRING = """ -Computes tangent for each element `x_i` for input array `x`. +Computes the tangent for each element :math:`x_i` for input array `x`. For full documentation refer to :obj:`numpy.tan`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + Input array, expected to have a floating-point data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -2520,8 +2520,8 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): Returns ------- out : dpnp.ndarray - An array containing the element-wise tangent. The data type - of the returned array is determined by the Type Promotion Rules. + An array containing the element-wise tangent, in radians. The data type of + the returned array is determined by the Type Promotion Rules. Limitations ----------- @@ -2531,7 +2531,7 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): See Also -------- -:obj:`dpnp.arctan` : Trigonometric inverse tangent, element-wise. +:obj:`dpnp.atan` : Trigonometric inverse tangent, element-wise. :obj:`dpnp.sin` : Trigonometric sine, element-wise. :obj:`dpnp.cos` : Trigonometric cosine, element-wise. :obj:`dpnp.tanh` : Hyperbolic tangent, element-wise. @@ -2555,15 +2555,21 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): ) -_TANH_DOCSTRING = """ -Computes hyperbolic tangent for each element `x_i` for input array `x`. +_TANH_DOCSTRING = r""" +Computes the hyperbolic tangent for each element :math:`x_i` for input array +`x`. + +The mathematical definition of the hyperbolic tangent is + +.. math:: + \operatorname{tanh}(x) = \frac{\operatorname{sinh}(x)}{\operatorname{cosh}(x)} For full documentation refer to :obj:`numpy.tanh`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + Input array, expected to have a floating-point data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -2577,8 +2583,8 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): Returns ------- out : dpnp.ndarray - An array containing the element-wise hyperbolic tangent. The data type - of the returned array is determined by the Type Promotion Rules. + An array containing the element-wise hyperbolic tangent. The data type of + the returned array is determined by the Type Promotion Rules. Limitations ----------- @@ -2588,7 +2594,7 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): See Also -------- -:obj:`dpnp.arctanh` : Hyperbolic inverse tangent, element-wise. +:obj:`dpnp.atanh` : Hyperbolic inverse tangent, element-wise. :obj:`dpnp.sinh` : Hyperbolic sine, element-wise. :obj:`dpnp.cosh` : Hyperbolic cosine, element-wise. :obj:`dpnp.tan` : Trigonometric tangent, element-wise. @@ -2617,8 +2623,9 @@ def unwrap(p, discont=None, axis=-1, *, period=2 * dpnp.pi): Unwrap by taking the complement of large deltas with respect to the period. This unwraps a signal `p` by changing elements which have an absolute - difference from their predecessor of more than ``max(discont, period / 2)`` - to their `period`-complementary values. + difference from their predecessor of more than + :math:`\max(discont, \frac{period}{2})` to their `period`-complementary + values. For the default case where `period` is :math:`2\pi` and `discont` is :math:`\pi`, this unwraps a radian phase `p` such that adjacent differences @@ -2633,16 +2640,19 @@ def unwrap(p, discont=None, axis=-1, *, period=2 * dpnp.pi): Input array. discont : {float, None}, optional Maximum discontinuity between values, default is ``None`` which is an - alias for ``period / 2``. Values below ``period / 2`` are treated as if - they were ``period / 2``. To have an effect different from the default, - `discont` should be larger than ``period / 2``. + alias for :math:`\frac{period}{2}`. Values below + :math:`\frac{period}{2}` are treated as if they were + :math:`\frac{period}{2}`. To have an effect different from the default, + `discont` should be larger than :math:`\frac{period}{2}`. Default: ``None``. axis : int, optional Axis along which unwrap will operate, default is the last axis. + Default: ``-1``. period : float, optional Size of the range over which the input wraps. + Default: ``2 * pi``. Returns @@ -2657,9 +2667,9 @@ def unwrap(p, discont=None, axis=-1, *, period=2 * dpnp.pi): Notes ----- - If the discontinuity in `p` is smaller than ``period / 2``, but larger than - `discont`, no unwrapping is done because taking the complement would only - make the discontinuity larger. + If the discontinuity in `p` is smaller than :math:`\frac{period}{2}`, but + larger than `discont`, no unwrapping is done because taking the complement + would only make the discontinuity larger. Examples -------- From 6a41c48ba959b316ab469b6cb2c874eca32a155c Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Fri, 4 Apr 2025 15:54:20 +0200 Subject: [PATCH 26/32] Rephrase see also link on dpnp.power --- dpnp/dpnp_iface_trigonometric.py | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/dpnp/dpnp_iface_trigonometric.py b/dpnp/dpnp_iface_trigonometric.py index b0474e4c9222..60697267720e 100644 --- a/dpnp/dpnp_iface_trigonometric.py +++ b/dpnp/dpnp_iface_trigonometric.py @@ -1188,8 +1188,7 @@ def cumlogsumexp( -------- :obj:`dpnp.exp` : Calculate :math:`e^x`, element-wise. :obj:`dpnp.expm1` : Calculate :math:`e^x - 1`, element-wise. -:obj:`dpnp.power` : Exponentiation by raising the first array to the power of - the second array, element-wise. +:obj:`dpnp.power` : Calculate :math:`{x1}^{x2}`, element-wise. Examples -------- @@ -2476,8 +2475,7 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): :obj:`dpnp..linalg.matrix_power` : Raise a square matrix to the (integer) power `n`. :obj:`dpnp.sqrt` : Calculate :math:`\sqrt{x}`, element-wise. -:obj:`dpnp.power` : Exponentiation by raising the first array to the power of - the second array, element-wise. +:obj:`dpnp.power` : Calculate :math:`{x1}^{x2}`, element-wise. Examples -------- From 8be126fcf663c53b103358a328721e6952942ab7 Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Mon, 7 Apr 2025 11:48:03 +0200 Subject: [PATCH 27/32] Update bitwise functions to add notes and to tune docstrings for input arrays --- dpnp/dpnp_iface_bitwise.py | 108 ++++++++++++++++++++++--------------- 1 file changed, 64 insertions(+), 44 deletions(-) diff --git a/dpnp/dpnp_iface_bitwise.py b/dpnp/dpnp_iface_bitwise.py index 0cfd8e6fcade..bbc9e465f20d 100644 --- a/dpnp/dpnp_iface_bitwise.py +++ b/dpnp/dpnp_iface_bitwise.py @@ -130,21 +130,17 @@ def binary_repr(num, width=None): _BITWISE_AND_DOCSTRING = """ Computes the bitwise AND of the underlying binary representation of each -element `x1_i` of the input array `x1` with the respective element `x2_i` -of the input array `x2`. +element :math:`x1_i` of the input array `x1` with the respective element +:math:`x2_i` of the input array `x2`. For full documentation refer to :obj:`numpy.bitwise_and`. Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have integer or boolean data type. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, expected to have an integer or boolean data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have integer or boolean data - type. Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also expected to have an integer or boolean data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -175,6 +171,13 @@ def binary_repr(num, width=None): :obj:`dpnp.binary_repr` : Return the binary representation of the input number as a string. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -206,6 +209,7 @@ def binary_repr(num, width=None): '1100' >>> np.bitwise_and(np.array([14, 3]), 13) array([12, 1]) + """ bitwise_and = DPNPBinaryFunc( @@ -225,7 +229,7 @@ def binary_repr(num, width=None): Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have integer or boolean data type. + Input array, expected to have an integer data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -272,21 +276,17 @@ def binary_repr(num, width=None): _BITWISE_OR_DOCSTRING = """ Computes the bitwise OR of the underlying binary representation of each -element `x1_i` of the input array `x1` with the respective element `x2_i` -of the input array `x2`. +element :math:`x1_i` of the input array `x1` with the respective element +:math:`x2_i` of the input array `x2`. For full documentation refer to :obj:`numpy.bitwise_or`. Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have integer or boolean data type. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, expected to have an integer or boolean data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have integer or boolean data - type. Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also expected to have an integer or boolean data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -317,6 +317,13 @@ def binary_repr(num, width=None): :obj:`dpnp.binary_repr` : Return the binary representation of the input number as a string. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -339,6 +346,7 @@ def binary_repr(num, width=None): array(29) >>> np.binary_repr(29) '11101' + """ bitwise_or = DPNPBinaryFunc( @@ -352,21 +360,17 @@ def binary_repr(num, width=None): _BITWISE_XOR_DOCSTRING = """ Computes the bitwise XOR of the underlying binary representation of each -element `x1_i` of the input array `x1` with the respective element `x2_i` -of the input array `x2`. +element :math:`x1_i` of the input array `x1` with the respective element +:math:`x2_i` of the input array `x2`. For full documentation refer to :obj:`numpy.bitwise_xor`. Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have integer or boolean data type. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, expected to have an integer or boolean data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have integer or boolean data - type. Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also expected to have an integer or boolean data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -397,6 +401,13 @@ def binary_repr(num, width=None): :obj:`dpnp.binary_repr` : Return the binary representation of the input number as a string. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -423,6 +434,7 @@ def binary_repr(num, width=None): array(28) >>> np.binary_repr(28) '11100' + """ bitwise_xor = DPNPBinaryFunc( @@ -435,7 +447,7 @@ def binary_repr(num, width=None): _INVERT_DOCSTRING = """ -Inverts (flips) each bit for each element `x_i` of the input array `x`. +Inverts (flips) each bit for each element :math:`x_i` of the input array `x`. Note that :obj:`dpnp.bitwise_invert` is an alias of :obj:`dpnp.invert`. @@ -444,7 +456,7 @@ def binary_repr(num, width=None): Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have integer or boolean data type. + Input array, expected to have an integer or boolean data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -514,9 +526,9 @@ def binary_repr(num, width=None): bitwise_invert = invert # bitwise_invert is an alias for invert _LEFT_SHIFT_DOCSTRING = """ -Shifts the bits of each element `x1_i` of the input array x1 to the left by -appending `x2_i` (i.e., the respective element in the input array `x2`) zeros to -the right of `x1_i`. +Shifts the bits of each element :math:`x1_i` of the input array `x1` to the +left by appending :math:`x2_i` (i.e., the respective element in the input array +`x2`) zeros to the right of :math:`x1_i`. Note that :obj:`dpnp.bitwise_left_shift` is an alias of :obj:`dpnp.left_shift`. @@ -525,14 +537,10 @@ def binary_repr(num, width=None): Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have integer data type. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, expected to have an integer data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have integer data type. + Second input array, also expected to have an integer data type. Each element must be greater than or equal to ``0``. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -560,6 +568,13 @@ def binary_repr(num, width=None): :obj:`dpnp.binary_repr` : Return the binary representation of the input number as a string. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -580,6 +595,7 @@ def binary_repr(num, width=None): array(20) >>> np.binary_repr(20) '10100' + """ left_shift = DPNPBinaryFunc( @@ -594,8 +610,8 @@ def binary_repr(num, width=None): _RIGHT_SHIFT_DOCSTRING = """ -Shifts the bits of each element `x1_i` of the input array `x1` to the right -according to the respective element `x2_i` of the input array `x2`. +Shifts the bits of each element :math:`x1_i` of the input array `x1` to the +right according to the respective element :math:`x2_i` of the input array `x2`. Note that :obj:`dpnp.bitwise_right_shift` is an alias of :obj:`dpnp.right_shift`. @@ -604,14 +620,10 @@ def binary_repr(num, width=None): Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have integer data type. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, expected to have an integer data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have integer data type. + Second input array, also expected to have an integer data type. Each element must be greater than or equal to ``0``. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -640,6 +652,13 @@ def binary_repr(num, width=None): :obj:`dpnp.binary_repr` : Return the binary representation of the input number as a string. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -660,6 +679,7 @@ def binary_repr(num, width=None): array(5) >>> np.binary_repr(5) '101' + """ right_shift = DPNPBinaryFunc( From b5683ffbd031312510f6b885025429ec5e49c244 Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Mon, 7 Apr 2025 12:53:47 +0200 Subject: [PATCH 28/32] Update logic functions to add notes and to tune docstrings for input arrays --- dpnp/dpnp_iface_logic.py | 235 +++++++++++++++++++++++---------------- 1 file changed, 140 insertions(+), 95 deletions(-) diff --git a/dpnp/dpnp_iface_logic.py b/dpnp/dpnp_iface_logic.py index 62d581ef9d63..a91e7a420c76 100644 --- a/dpnp/dpnp_iface_logic.py +++ b/dpnp/dpnp_iface_logic.py @@ -84,7 +84,7 @@ def all(a, /, axis=None, out=None, keepdims=False, *, where=True): """ - Test whether all array elements along a given axis evaluate to True. + Test whether all array elements along a given axis evaluate to ``True``. For full documentation refer to :obj:`numpy.all`. @@ -129,9 +129,9 @@ def all(a, /, axis=None, out=None, keepdims=False, *, where=True): See Also -------- - :obj:`dpnp.ndarray.all` : equivalent method + :obj:`dpnp.ndarray.all` : Equivalent method. :obj:`dpnp.any` : Test whether any element along a given axis evaluates - to True. + to ``True``. Notes ----- @@ -196,10 +196,8 @@ def allclose(a, b, rtol=1.0e-5, atol=1.0e-8, equal_nan=False): ---------- a : {dpnp.ndarray, usm_ndarray, scalar} First input array, expected to have numeric data type. - Both inputs `a` and `b` can not be scalars at the same time. b : {dpnp.ndarray, usm_ndarray, scalar} Second input array, also expected to have numeric data type. - Both inputs `a` and `b` can not be scalars at the same time. rtol : {dpnp.ndarray, usm_ndarray, scalar}, optional The relative tolerance parameter. @@ -229,6 +227,8 @@ def allclose(a, b, rtol=1.0e-5, atol=1.0e-8, equal_nan=False): Notes ----- + At least one of `x1` or `x2` must be an array. + The comparison of `a` and `b` uses standard broadcasting, which means that `a` and `b` need not have the same shape in order for ``dpnp.allclose(a, b)`` to evaluate to ``True``. @@ -261,7 +261,7 @@ def allclose(a, b, rtol=1.0e-5, atol=1.0e-8, equal_nan=False): def any(a, /, axis=None, out=None, keepdims=False, *, where=True): """ - Test whether any array element along a given axis evaluates to True. + Test whether any array element along a given axis evaluates to ``True``. For full documentation refer to :obj:`numpy.any`. @@ -306,9 +306,9 @@ def any(a, /, axis=None, out=None, keepdims=False, *, where=True): See Also -------- - :obj:`dpnp.ndarray.any` : equivalent method + :obj:`dpnp.ndarray.any` : Equivalent method. :obj:`dpnp.all` : Test whether all elements along a given axis evaluate - to True. + to ``True``. Notes ----- @@ -365,10 +365,8 @@ def array_equal(a1, a2, equal_nan=False): ---------- a1 : {dpnp.ndarray, usm_ndarray, scalar} First input array. - Both inputs `x1` and `x2` can not be scalars at the same time. a2 : {dpnp.ndarray, usm_ndarray, scalar} Second input array. - Both inputs `x1` and `x2` can not be scalars at the same time. equal_nan : bool, optional Whether to compare ``NaNs`` as equal. If the dtype of `a1` and `a2` is complex, values will be considered equal if either the real or the @@ -388,6 +386,10 @@ def array_equal(a1, a2, equal_nan=False): :obj:`dpnp.array_equiv`: Returns ``True`` if input arrays are shape consistent and all elements equal. + Notes + ----- + At least one of `x1` or `x2` must be an array. + Examples -------- >>> import dpnp as np @@ -490,10 +492,8 @@ def array_equiv(a1, a2): ---------- a1 : {dpnp.ndarray, usm_ndarray, scalar} First input array. - Both inputs `x1` and `x2` can not be scalars at the same time. a2 : {dpnp.ndarray, usm_ndarray, scalar} Second input array. - Both inputs `x1` and `x2` can not be scalars at the same time. Returns ------- @@ -501,6 +501,10 @@ def array_equiv(a1, a2): A 0-d array with ``True`` value if the arrays are equivalent, ``False`` otherwise. + Notes + ----- + At least one of `x1` or `x2` must be an array. + Examples -------- >>> import dpnp as np @@ -540,21 +544,17 @@ def array_equiv(a1, a2): _EQUAL_DOCSTRING = """ -Calculates equality test results for each element `x1_i` of the input array `x1` -with the respective element `x2_i` of the input array `x2`. +Calculates equality test results for each element :math:`x1_i` of the input +array `x1` with the respective element :math:`x2_i` of the input array `x2`. For full documentation refer to :obj:`numpy.equal`. Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, expected to have a boolean or numeric data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also expected to have a boolean or numeric data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array have the correct shape and the expected data type. @@ -583,6 +583,13 @@ def array_equiv(a1, a2): :obj:`dpnp.greater` : Return the truth value of (x1 > x2) element-wise. :obj:`dpnp.less` : Return the truth value of (x1 < x2) element-wise. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -616,21 +623,18 @@ def array_equiv(a1, a2): _GREATER_DOCSTRING = """ -Computes the greater-than test results for each element `x1_i` of -the input array `x1` with the respective element `x2_i` of the input array `x2`. +Computes the greater-than test results for each element :math:`x1_i` of the +input array `x1` with the respective element :math:`x2_i` of the input array +`x2`. For full documentation refer to :obj:`numpy.greater`. Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, expected to have a boolean or numeric data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also expected to have a boolean or numeric data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -659,6 +663,13 @@ def array_equiv(a1, a2): :obj:`dpnp.equal` : Return (x1 == x2) element-wise. :obj:`dpnp.not_equal` : Return (x1 != x2) element-wise. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -686,21 +697,18 @@ def array_equiv(a1, a2): _GREATER_EQUAL_DOCSTRING = """ -Computes the greater-than or equal-to test results for each element `x1_i` of -the input array `x1` with the respective element `x2_i` of the input array `x2`. +Computes the greater-than or equal-to test results for each element :math:`x1_i` +of the input array `x1` with the respective element :math:`x2_i` of the input +array `x2`. For full documentation refer to :obj:`numpy.greater_equal`. Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, expected to have a boolean or numeric data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also expected to have a boolean or numeric data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -730,6 +738,13 @@ def array_equiv(a1, a2): :obj:`dpnp.equal` : Return (x1 == x2) element-wise. :obj:`dpnp.not_equal` : Return (x1 != x2) element-wise. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -749,7 +764,7 @@ def array_equiv(a1, a2): """ greater_equal = DPNPBinaryFunc( - "greater", + "greater_equal", ti._greater_equal_result_type, ti._greater_equal, _GREATER_EQUAL_DOCSTRING, @@ -776,10 +791,8 @@ def isclose(a, b, rtol=1e-05, atol=1e-08, equal_nan=False): ---------- a : {dpnp.ndarray, usm_ndarray, scalar} First input array, expected to have numeric data type. - Both inputs `a` and `b` can not be scalars at the same time. b : {dpnp.ndarray, usm_ndarray, scalar} Second input array, also expected to have numeric data type. - Both inputs `a` and `b` can not be scalars at the same time. rtol : {dpnp.ndarray, usm_ndarray, scalar}, optional The relative tolerance parameter. @@ -805,6 +818,10 @@ def isclose(a, b, rtol=1e-05, atol=1e-08, equal_nan=False): :obj:`dpnp.allclose` : Returns ``True`` if two arrays are element-wise equal within a tolerance. + Notes + ----- + At least one of `x1` or `x2` must be an array. + Examples -------- >>> import dpnp as np @@ -968,14 +985,14 @@ def iscomplexobj(x): _ISFINITE_DOCSTRING = """ -Test if each element of input array is a finite number. +Test each element :math:`x_i` of input array `x` if finite. For full documentation refer to :obj:`numpy.isfinite`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + Input array, expected to have a boolean or numeric data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -1099,14 +1116,15 @@ def isfortran(a): _ISINF_DOCSTRING = """ -Test if each element of input array is an infinity. +Tests each element :math:`x_i` of the input array `x` to determine if equal to +positive or negative infinity. For full documentation refer to :obj:`numpy.isinf`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + Input array, expected to have a boolean or numeric data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -1156,14 +1174,15 @@ def isfortran(a): _ISNAN_DOCSTRING = """ -Test if each element of an input array is a NaN. +Tests each element :math:`x_i` of the input array `x` to determine whether the +element is ``NaN``. For full documentation refer to :obj:`numpy.isnan`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + Input array, expected to have a boolean or numeric data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -1490,21 +1509,17 @@ def isscalar(element): _LESS_DOCSTRING = """ -Computes the less-than test results for each element `x1_i` of -the input array `x1` with the respective element `x2_i` of the input array `x2`. +Computes the less-than test results for each element :math:`x1_i` of the input +array `x1` with the respective element :math:`x2_i` of the input array `x2`. For full documentation refer to :obj:`numpy.less`. Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, expected to have a boolean or numeric data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also expected to have a boolean or numeric data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -1533,6 +1548,13 @@ def isscalar(element): :obj:`dpnp.equal` : Return (x1 == x2) element-wise. :obj:`dpnp.not_equal` : Return (x1 != x2) element-wise. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -1560,21 +1582,18 @@ def isscalar(element): _LESS_EQUAL_DOCSTRING = """ -Computes the less-than or equal-to test results for each element `x1_i` of -the input array `x1` with the respective element `x2_i` of the input array `x2`. +Computes the less-than or equal-to test results for each element :math:`x1_i` +of the input array `x1` with the respective element :math:`x2_i` of the input +array `x2`. For full documentation refer to :obj:`numpy.less_equal`. Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, expected to have a boolean or numeric data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also expected to have a boolean or numeric data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -1603,6 +1622,13 @@ def isscalar(element): :obj:`dpnp.equal` : Return (x1 == x2) element-wise. :obj:`dpnp.not_equal` : Return (x1 != x2) element-wise. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -1630,21 +1656,17 @@ def isscalar(element): _LOGICAL_AND_DOCSTRING = """ -Computes the logical AND for each element `x1_i` of the input array `x1` with -the respective element `x2_i` of the input array `x2`. +Computes the logical AND for each element :math:`x1_i` of the input array `x1` +with the respective element :math:`x2_i` of the input array `x2`. For full documentation refer to :obj:`numpy.logical_and`. Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, expected to have a boolean or numeric data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also expected to have a boolean or numeric data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -1672,6 +1694,13 @@ def isscalar(element): :obj:`dpnp.logical_xor` : Compute the truth value of x1 XOR x2, element-wise. :obj:`dpnp.bitwise_and` : Compute the bit-wise AND of two arrays element-wise. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -1703,14 +1732,14 @@ def isscalar(element): _LOGICAL_NOT_DOCSTRING = """ -Computes the logical NOT for each element `x_i` of input array `x`. +Computes the logical NOT for each element :math:`x_i` of input array `x`. For full documentation refer to :obj:`numpy.logical_not`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array. + Input array, expected to have a boolean or numeric data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -1737,6 +1766,13 @@ def isscalar(element): :obj:`dpnp.logical_or` : Compute the truth value of x1 OR x2 element-wise. :obj:`dpnp.logical_xor` : Compute the truth value of x1 XOR x2, element-wise. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -1759,21 +1795,17 @@ def isscalar(element): _LOGICAL_OR_DOCSTRING = """ -Computes the logical OR for each element `x1_i` of the input array `x1` -with the respective element `x2_i` of the input array `x2`. +Computes the logical OR for each element :math:`x1_i` of the input array `x1` +with the respective element :math:`x2_i` of the input array `x2`. For full documentation refer to :obj:`numpy.logical_or`. Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, expected to have a boolean or numeric data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also expected to have a boolean or numeric data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -1801,6 +1833,13 @@ def isscalar(element): :obj:`dpnp.logical_xor` : Compute the truth value of x1 XOR x2, element-wise. :obj:`dpnp.bitwise_or` : Compute the bit-wise OR of two arrays element-wise. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -1832,21 +1871,17 @@ def isscalar(element): _LOGICAL_XOR_DOCSTRING = """ -Computes the logical XOR for each element `x1_i` of the input array `x1` -with the respective element `x2_i` of the input array `x2`. +Computes the logical XOR for each element :math:`x1_i` of the input array `x1` +with the respective element :math:`x2_i` of the input array `x2`. For full documentation refer to :obj:`numpy.logical_xor`. Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, expected to have a boolean or numeric data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also expected to have a boolean or numeric data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -1874,6 +1909,13 @@ def isscalar(element): :obj:`dpnp.logical_not` : Compute the truth value of NOT x element-wise. :obj:`dpnp.bitwise_xor` : Compute the bit-wise XOR of two arrays element-wise. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -1903,21 +1945,17 @@ def isscalar(element): _NOT_EQUAL_DOCSTRING = """ -Calculates inequality test results for each element `x1_i` of the -input array `x1` with the respective element `x2_i` of the input array `x2`. +Calculates inequality test results for each element :math:`x1_i` of the input +array `x1` with the respective element :math:`x2_i` of the input array `x2`. For full documentation refer to :obj:`numpy.not_equal`. Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, expected to have a boolean or numeric data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also expected to have a boolean or numeric data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -1946,6 +1984,13 @@ def isscalar(element): :obj:`dpnp.less` : Return the truth value of (x1 < x2) element-wise. :obj:`dpnp.less_equal` : Return the truth value of (x1 =< x2) element-wise. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np From bb711a1b399d032d6001853520782aa796ef228c Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Mon, 7 Apr 2025 20:52:07 +0200 Subject: [PATCH 29/32] Update math functions to add notes and to tune docstrings for input arrays --- dpnp/dpnp_iface_mathematical.py | 560 +++++++++++++++++++------------- 1 file changed, 336 insertions(+), 224 deletions(-) diff --git a/dpnp/dpnp_iface_mathematical.py b/dpnp/dpnp_iface_mathematical.py index a071351c10a3..f65fdf16f8c4 100644 --- a/dpnp/dpnp_iface_mathematical.py +++ b/dpnp/dpnp_iface_mathematical.py @@ -349,14 +349,14 @@ def _process_ediff1d_args(arg, arg_name, ary_dtype, ary_sycl_queue, usm_type): _ABS_DOCSTRING = """ -Calculates the absolute value for each element `x_i` of input array `x`. +Calculates the absolute value for each element :math:`x_i` of input array `x`. -For full documentation refer to :obj:`numpy.absolute`. +For full documentation refer to :obj:`numpy.abs`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + Input array, expected to have a boolean or numeric data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -372,8 +372,8 @@ def _process_ediff1d_args(arg, arg_name, ary_dtype, ary_sycl_queue, usm_type): out : dpnp.ndarray An array containing the element-wise absolute values. For complex input, the absolute value is its magnitude. - If `x` has a real-valued floating-point data type, the returned array has the - same data type as `x`. If `x` has a complex floating-point data type, + If `x` has a real-valued floating-point data type, the returned array has + the same data type as `x`. If `x` has a complex floating-point data type, the returned array has a real-valued floating-point data type whose precision matches the precision of `x`. @@ -389,21 +389,22 @@ def _process_ediff1d_args(arg, arg_name, ary_dtype, ary_sycl_queue, usm_type): Notes ----- -``dpnp.abs`` is a shorthand for this function. +``dpnp.absolute`` is a shorthand for this function. Examples -------- >>> import dpnp as np >>> a = np.array([-1.2, 1.2]) ->>> np.absolute(a) +>>> np.abs(a) array([1.2, 1.2]) >>> a = np.array(1.2 + 1j) ->>> np.absolute(a) +>>> np.abs(a) array(1.5620499351813308) + """ -absolute = DPNPUnaryFunc( +abs = DPNPUnaryFunc( "abs", ti._abs_result_type, ti._abs, @@ -413,25 +414,21 @@ def _process_ediff1d_args(arg, arg_name, ary_dtype, ary_sycl_queue, usm_type): ) -abs = absolute +absolute = abs _ADD_DOCSTRING = """ -Calculates the sum for each element `x1_i` of the input array `x1` with -the respective element `x2_i` of the input array `x2`. +Calculates the sum for each element :math:`x1_i` of the input array `x1` with +the respective element :math:`x2_i` of the input array `x2`. For full documentation refer to :obj:`numpy.add`. Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, expected to have a boolean or numeric data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also expected to have a boolean or numeric data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -456,7 +453,12 @@ def _process_ediff1d_args(arg, arg_name, ary_dtype, ary_sycl_queue, usm_type): Notes ----- -Equivalent to `x1` + `x2` in terms of array broadcasting. +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + +Equivalent to :math:`x1 + x2` in terms of array broadcasting. Examples -------- @@ -480,6 +482,7 @@ def _process_ediff1d_args(arg, arg_name, ary_dtype, ary_sycl_queue, usm_type): array([[ 0., 2., 4.], [ 3., 5., 7.], [ 6., 8., 10.]]) + """ @@ -495,15 +498,15 @@ def _process_ediff1d_args(arg, arg_name, ary_dtype, ary_sycl_queue, usm_type): _ANGLE_DOCSTRING = """ -Computes the phase angle (also called the argument) of each element `x_i` for -input array `x`. +Computes the phase angle (also called the argument) of each element :math:`x_i` +for input array `x`. For full documentation refer to :obj:`numpy.angle`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have a complex-valued floating-point data type. + Input array, expected to have a complex floating-point data type. deg : bool, optional Return angle in degrees if ``True``, radians if ``False``. @@ -527,17 +530,19 @@ def _process_ediff1d_args(arg, arg_name, ary_dtype, ary_sycl_queue, usm_type): Notes ----- -Although the angle of the complex number 0 is undefined, `dpnp.angle(0)` returns the value 0. +Although the angle of the complex number 0 is undefined, `dpnp.angle(0)` returns +the value ``0``. See Also -------- -:obj:`dpnp.arctan2` : Element-wise arc tangent of `x1/x2` choosing the quadrant correctly. -:obj:`dpnp.arctan` : Trigonometric inverse tangent, element-wise. -:obj:`dpnp.absolute` : Calculate the absolute value element-wise. +:obj:`dpnp.atan2` : Element-wise arc tangent of `x1/x2` choosing the quadrant + correctly. +:obj:`dpnp.atan` : Trigonometric inverse tangent, element-wise. +:obj:`dpnp.abs` : Calculate the absolute value element-wise. :obj:`dpnp.real` : Return the real part of the complex argument. :obj:`dpnp.imag` : Return the imaginary part of the complex argument. :obj:`dpnp.real_if_close` : Return the real part of the input is complex - with all imaginary parts close to zero. + with all imaginary parts close to zero. Examples -------- @@ -548,6 +553,7 @@ def _process_ediff1d_args(arg, arg_name, ary_dtype, ary_sycl_queue, usm_type): >>> np.angle(a, deg=True) # in degrees array([ 0., 90., 45.]) + """ angle = DPNPAngle( @@ -604,14 +610,17 @@ def around(x, /, decimals=0, out=None): _CEIL_DOCSTRING = """ -Returns the ceiling for each element `x_i` for input array `x`. +Returns the ceiling for each element :math:`x_i` for input array `x`. +Rounds each element :math:`x_i` of the input array `x` to the smallest (i.e., +closest to ``-infinity``) integer-valued number that is not less than +:math:`x_i`. For full documentation refer to :obj:`numpy.ceil`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have a real-valued floating-point data type. + Input array, expected to have a boolean or real-valued data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -646,6 +655,7 @@ def around(x, /, decimals=0, out=None): >>> a = np.array([-1.7, -1.5, -0.2, 0.2, 1.5, 1.7, 2.0]) >>> np.ceil(a) array([-1.0, -1.0, -0.0, 1.0, 2.0, 2.0, 2.0]) + """ ceil = DPNPUnaryFunc( @@ -740,14 +750,15 @@ def clip(a, /, min=None, max=None, *, out=None, order="K", **kwargs): _CONJ_DOCSTRING = """ -Computes conjugate of each element `x_i` for input array `x`. +Returns the complex conjugate for each element :math:`x_i` of the input array +`x`. For full documentation refer to :obj:`numpy.conj`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + Input array, expected to have a boolean or numeric data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -771,16 +782,16 @@ def clip(a, /, min=None, max=None, *, out=None, order="K", **kwargs): Examples -------- >>> import dpnp as np ->>> np.conjugate(np.array(1+2j)) +>>> np.conj(np.array(1+2j)) (1-2j) >>> x = np.eye(2) + 1j * np.eye(2) ->>> np.conjugate(x) +>>> np.conj(x) array([[ 1.-1.j, 0.-0.j], [ 0.-0.j, 1.-1.j]]) """ -conjugate = DPNPUnaryFunc( +conj = DPNPUnaryFunc( "conj", ti._conj_result_type, ti._conj, @@ -789,11 +800,11 @@ def clip(a, /, min=None, max=None, *, out=None, order="K", **kwargs): mkl_impl_fn="_conj", ) -conj = conjugate +conjugate = conj _COPYSIGN_DOCSTRING = """ -Composes a floating-point value with the magnitude of `x1_i` and the sign of -`x2_i` for each element of input arrays `x1` and `x2`. +Composes a floating-point value with the magnitude of :math:`x1_i` and the sign +of :math:`x2_i` for each element of the input array `x1`. For full documentation refer to :obj:`numpy.copysign`. @@ -801,13 +812,9 @@ def clip(a, /, min=None, max=None, *, out=None, order="K", **kwargs): ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} First input array, expected to have a real-valued floating-point data type. - Both inputs `x1` and `x2` can not be scalars at the same time. x2 : {dpnp.ndarray, usm_ndarray, scalar} Second input array, also expected to have a real-valued floating-point data type. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -835,6 +842,13 @@ def clip(a, /, min=None, max=None, *, out=None, order="K", **kwargs): :obj:`dpnp.negative` : Return the numerical negative of each element of `x`. :obj:`dpnp.positive` : Return the numerical positive of each element of `x`. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -1476,22 +1490,18 @@ def diff(a, n=1, axis=-1, prepend=None, append=None): return dpnp_array._create_from_usm_ndarray(usm_res) -_DIVIDE_DOCSTRING = """ -Calculates the ratio for each element `x1_i` of the input array `x1` with -the respective element `x2_i` of the input array `x2`. +_DIVIDE_DOCSTRING = r""" +Calculates the ratio for each element :math:`x1_i` of the input array `x1` with +the respective element :math:`x2_i` of the input array `x2`. For full documentation refer to :obj:`numpy.divide`. Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, expected to have a floating-point data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also expected to have a floating-point data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -1516,10 +1526,14 @@ def diff(a, n=1, axis=-1, prepend=None, append=None): Notes ----- -Equivalent to `x1` / `x2` in terms of array-broadcasting. +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + +Equivalent to :math:`\frac{x1}{x2}` in terms of array-broadcasting. -The ``true_divide(x1, x2)`` function is an alias for -``divide(x1, x2)``. +The ``true_divide(x1, x2)`` function is an alias for ``divide(x1, x2)``. Examples -------- @@ -1543,6 +1557,7 @@ def diff(a, n=1, axis=-1, prepend=None, append=None): array([[0. , 0.5, 1. ], [1.5, 2. , 2.5], [3. , 3.5, 4. ]]) + """ divide = DPNPBinaryFunc( @@ -1696,6 +1711,7 @@ def ediff1d(ary, to_end=None, to_begin=None): >>> a = np.array([-1.2, 1.2]) >>> np.fabs(a) array([1.2, 1.2]) + """ fabs = DPNPUnaryFunc( @@ -1757,6 +1773,7 @@ def ediff1d(ary, to_end=None, to_begin=None): >>> a = np.array([2.1, 2.9, -2.1, -2.9]) >>> np.fix(a) array([ 2., 2., -2., -2.]) + """ fix = DPNPFix( @@ -1768,8 +1785,9 @@ def ediff1d(ary, to_end=None, to_begin=None): _FLOAT_POWER_DOCSTRING = """ -Calculates `x1_i` raised to `x2_i` for each element `x1_i` of the input array -`x1` with the respective element `x2_i` of the input array `x2`. +Calculates :math:`x1_i` raised to :math:`x2_i` for each element :math:`x1_i` of +the input array `x1` with the respective element :math:`x2_i` of the input +array `x2`. This differs from the power function in that boolean, integers, and float16 are promoted to floats with a minimum precision of float32 so that the result is @@ -1785,13 +1803,9 @@ def ediff1d(ary, to_end=None, to_begin=None): Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have floating-point data types. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, expected to have a numeric data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to floating-point data types. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also expected to a numeric data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -1818,6 +1832,13 @@ def ediff1d(ary, to_end=None, to_begin=None): -------- :obj:`dpnp.power` : Power function that preserves type. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -1857,6 +1878,7 @@ def ediff1d(ary, to_end=None, to_begin=None): >>> np.float_power(x3, 1.5, dtype=np.complex64) array([1.1924881e-08-1.j, 9.5399045e-08-8.j], dtype=complex64) + """ float_power = DPNPBinaryFunc( @@ -1871,16 +1893,16 @@ def ediff1d(ary, to_end=None, to_begin=None): _FLOOR_DOCSTRING = """ -Returns the floor for each element `x_i` for input array `x`. +Returns the floor for each element :math:`x_i` for input array `x`. -The floor of `x_i` is the largest integer `n`, such that `n <= x_i`. +The floor of :math:`x_i` is the largest integer `n`, such that `n <= x_i`. For full documentation refer to :obj:`numpy.floor`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have a real-valued floating-point data type. + Input array, expected to have a boolean or real-valued data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -1922,6 +1944,7 @@ def ediff1d(ary, to_end=None, to_begin=None): >>> a = np.array([-1.7, -1.5, -0.2, 0.2, 1.5, 1.7, 2.0]) >>> np.floor(a) array([-2.0, -2.0, -1.0, 0.0, 1.0, 1.0, 2.0]) + """ floor = DPNPUnaryFunc( @@ -1935,22 +1958,19 @@ def ediff1d(ary, to_end=None, to_begin=None): _FLOOR_DIVIDE_DOCSTRING = """ -Calculates the ratio for each element `x1_i` of the input array `x1` with -the respective element `x2_i` of the input array `x2` to the greatest -integer-value number that is not greater than the division result. +Rounds the result of dividing each element :math:`x1_i` of the input array `x1` +by the respective element :math:`x2_i` of the input array `x2` to the greatest +(i.e., closest to ``+infinity``) integer-value number that is not greater than +the division result. For full documentation refer to :obj:`numpy.floor_divide`. Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, expected to have a real-valued data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also expected to have a real-valued data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -1981,6 +2001,13 @@ def ediff1d(ary, to_end=None, to_begin=None): :obj:`dpnp.floor` : Round a number to the nearest integer toward minus infinity. :obj:`dpnp.ceil` : Round a number to the nearest integer toward infinity. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -1996,6 +2023,7 @@ def ediff1d(ary, to_end=None, to_begin=None): >>> x1 = np.array([1., 2., 3., 4.]) >>> x1 // 2.5 array([0., 0., 1., 1.]) + """ floor_divide = DPNPBinaryFunc( @@ -2011,7 +2039,7 @@ def ediff1d(ary, to_end=None, to_begin=None): Compares two input arrays `x1` and `x2` 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 +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 @@ -2022,13 +2050,9 @@ def ediff1d(ary, to_end=None, to_begin=None): Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, expected to have a boolean or numeric data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also expected to have a boolean or numeric data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -2063,6 +2087,11 @@ def ediff1d(ary, to_end=None, to_begin=None): Notes ----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + ``fmax(x1, x2)`` is equivalent to ``dpnp.where(x1 >= x2, x1, x2)`` when neither `x1` nor `x2` are NaNs, but it is faster and does proper broadcasting. @@ -2084,6 +2113,7 @@ def ediff1d(ary, to_end=None, to_begin=None): >>> x2 = np.array([0, np.nan, np.nan]) >>> np.fmax(x1, x2) array([ 0., 0., nan]) + """ fmax = DPNPBinaryFunc( @@ -2100,7 +2130,7 @@ def ediff1d(ary, to_end=None, to_begin=None): Compares two input arrays `x1` and `x2` 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 +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 @@ -2111,13 +2141,9 @@ def ediff1d(ary, to_end=None, to_begin=None): Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, expected to have a boolean or numeric data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also expected to have a boolean or numeric data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -2152,6 +2178,11 @@ def ediff1d(ary, to_end=None, to_begin=None): Notes ----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + ``fmin(x1, x2)`` is equivalent to ``dpnp.where(x1 <= x2, x1, x2)`` when neither `x1` nor `x2` are NaNs, but it is faster and does proper broadcasting. @@ -2173,6 +2204,7 @@ def ediff1d(ary, to_end=None, to_begin=None): >>> x2 = np.array([0, np.nan, np.nan]) >>> np.fmin(x1, x2) array([ 0., 0., nan]) + """ fmin = DPNPBinaryFunc( @@ -2186,8 +2218,8 @@ def ediff1d(ary, to_end=None, to_begin=None): _FMOD_DOCSTRING = """ -Calculates the remainder of division for each element `x1_i` of the input array -`x1` with the respective element `x2_i` of the input array `x2`. +Calculates the remainder of division for each element :math:`x1_i` of the input array +`x1` with the respective element :math:`x2_i` of the input array `x2`. This function is equivalent to the Matlab(TM) ``rem`` function and should not be confused with the Python modulus operator ``x1 % x2``. @@ -2197,13 +2229,10 @@ def ediff1d(ary, to_end=None, to_begin=None): Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have a real-valued floating-point data type. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, expected to have a boolean or real-valued data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have a real-valued floating-point data type. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also expected to have a boolean or real-valued data + type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -2231,6 +2260,13 @@ def ediff1d(ary, to_end=None, to_begin=None): :obj:`dpnp.remainder` : Equivalent to the Python ``%`` operator. :obj:`dpnp.divide` : Standard division. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -2251,6 +2287,7 @@ def ediff1d(ary, to_end=None, to_begin=None): array([[-1, 0], [-1, 0], [ 1, 0]]) + """ fmod = DPNPBinaryFunc( @@ -2262,8 +2299,8 @@ def ediff1d(ary, to_end=None, to_begin=None): mkl_impl_fn="_fmod", ) -_GCD_DOCSTRING = """ -Returns the greatest common divisor of ``|x1|`` and ``|x2|``. +_GCD_DOCSTRING = r""" +Returns the greatest common divisor of :math:`\abs{x1}` and :math:`\abs{x2}`. For full documentation refer to :obj:`numpy.gcd`. @@ -2271,12 +2308,8 @@ def ediff1d(ary, to_end=None, to_begin=None): ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} First input array, expected to have an integer data type. - Both inputs `x1` and `x2` can not be scalars at the same time. x2 : {dpnp.ndarray, usm_ndarray, scalar} Second input array, also expected to have an integer data type. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -2302,6 +2335,13 @@ def ediff1d(ary, to_end=None, to_begin=None): -------- :obj:`dpnp.lcm` : The lowest common multiple. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -2309,6 +2349,7 @@ def ediff1d(ary, to_end=None, to_begin=None): array(4) >>> np.gcd(np.arange(6), 20) array([20, 1, 2, 1, 4, 5]) + """ gcd = DPNPBinaryFunc( @@ -2539,13 +2580,10 @@ def gradient(f, *varargs, axis=None, edge_order=1): Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - Input values. - Both inputs `x1` and `x2` can not be scalars at the same time. + Input values, expected to have a real-valued floating-point data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - The value of the function when `x1` is ``0``. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + The value of the function when `x1` is ``0``, also expected to have a + real-valued floating-point data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -2567,6 +2605,13 @@ def gradient(f, *varargs, axis=None, edge_order=1): Keyword argument `kwargs` is currently unsupported. Otherwise ``NotImplementedError`` exception will be raised. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -2575,6 +2620,7 @@ def gradient(f, *varargs, axis=None, edge_order=1): array([0. , 0.5, 1. ]) >>> np.heaviside(a, 1) array([0., 1., 1.]) + """ heaviside = DPNPBinaryFunc( @@ -2595,7 +2641,8 @@ def gradient(f, *varargs, axis=None, edge_order=1): Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Argument of the Bessel function, expected to have floating-point data type. + Argument of the Bessel function, expected to have a real-valued + floating-point data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -2621,6 +2668,7 @@ def gradient(f, *varargs, axis=None, edge_order=1): array(1.) >>> np.i0(np.array([0, 1, 2, 3])) array([1. , 1.26606588, 2.2795853 , 4.88079259]) + """ i0 = DPNPI0( @@ -2632,14 +2680,15 @@ def gradient(f, *varargs, axis=None, edge_order=1): _IMAG_DOCSTRING = """ -Computes imaginary part of each element `x_i` for input array `x`. +Returns the imaginary component of a complex number for each element :math:`x_i` +of the input array `x`. For full documentation refer to :obj:`numpy.imag`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + Input array, expected to have a boolean or numeric data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -2681,6 +2730,7 @@ def gradient(f, *varargs, axis=None, edge_order=1): >>> np.imag(np.array(1 + 1j)) array(1.) + """ imag = DPNPImag( @@ -2691,8 +2741,8 @@ def gradient(f, *varargs, axis=None, edge_order=1): ) -_LCM_DOCSTRING = """ -Returns the lowest common multiple of ``|x1|`` and ``|x2|``. +_LCM_DOCSTRING = r""" +Returns the lowest common multiple of :math:`\abs{x1}` and :math:`\abs{x2}`. For full documentation refer to :obj:`numpy.lcm`. @@ -2700,12 +2750,8 @@ def gradient(f, *varargs, axis=None, edge_order=1): ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} First input array, expected to have an integer data type. - Both inputs `x1` and `x2` can not be scalars at the same time. x2 : {dpnp.ndarray, usm_ndarray, scalar} Second input array, also expected to have an integer data type. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -2731,6 +2777,13 @@ def gradient(f, *varargs, axis=None, edge_order=1): -------- :obj:`dpnp.gcd` : The greatest common divisor. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -2738,6 +2791,7 @@ def gradient(f, *varargs, axis=None, edge_order=1): array(60) >>> np.lcm(np.arange(6), 20) array([ 0, 20, 20, 60, 20, 20]) + """ lcm = DPNPBinaryFunc( @@ -2750,23 +2804,20 @@ def gradient(f, *varargs, axis=None, edge_order=1): _LDEXP_DOCSTRING = """ -Returns x1 * 2**x2, element-wise. +Returns :math:`x1 * 2^{x2}`, element-wise. -The mantissas `x1` and exponents of two `x2` are used to construct floating point -numbers ``x1 * 2**x2``. +The mantissas `x1` and exponents of two `x2` are used to construct +floating-point numbers :math:`x1 * 2^{x2}`. For full documentation refer to :obj:`numpy.ldexp`. Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - Array of multipliers, expected to have floating-point data types. - Both inputs `x1` and `x2` can not be scalars at the same time. + Array of multipliers, expected to have a real-valued floating-point data + type. x2 : {dpnp.ndarray, usm_ndarray, scalar} Array of exponents of two, expected to have an integer data type. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -2780,7 +2831,7 @@ def gradient(f, *varargs, axis=None, edge_order=1): Returns ------- out : dpnp.ndarray - The result of ``x1 * 2**x2``. + The result of :math:`x1 * 2^{x2}`. Limitations ----------- @@ -2790,20 +2841,27 @@ def gradient(f, *varargs, axis=None, edge_order=1): See Also -------- -:obj:`dpnp.frexp` : Return (y1, y2) from ``x = y1 * 2**y2``, inverse to :obj:`dpnp.ldexp`. +:obj:`dpnp.frexp` : Return (y1, y2) from :math:`x = y1 * 2^{y2}`, + inverse to :obj:`dpnp.ldexp`. Notes ----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Complex dtypes are not supported, they will raise a ``TypeError``. :obj:`dpnp.ldexp` is useful as the inverse of :obj:`dpnp.frexp`, if used by -itself it is more clear to simply use the expression ``x1 * 2**x2``. +itself it is more clear to simply use the expression :math:`x1 * 2^{x2}`. Examples -------- >>> import dpnp as np >>> np.ldexp(5, np.arange(4)) array([ 5., 10., 20., 40.]) + """ ldexp = DPNPBinaryFunc( @@ -2816,26 +2874,23 @@ def gradient(f, *varargs, axis=None, edge_order=1): _MAXIMUM_DOCSTRING = """ -Compares two input arrays `x1` and `x2` and returns a new array containing the -element-wise maxima. +Computes the maximum value for each element :math:`x1_i` of the input array `x1` +relative to the respective element :math:`x2_i` of the input array `x2`. -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. +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. For full documentation refer to :obj:`numpy.maximum`. Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, expected to have a boolean or numeric data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also expected to have a boolean or numeric data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -2868,6 +2923,13 @@ def gradient(f, *varargs, axis=None, edge_order=1): :obj:`dpnp.min` : The minimum value of an array along a given axis, propagates NaNs. :obj:`dpnp.nanmin` : The minimum value of an array along a given axis, ignores NaNs. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -2889,6 +2951,7 @@ def gradient(f, *varargs, axis=None, edge_order=1): >>> np.maximum(np.array(np.inf), 1) array(inf) + """ maximum = DPNPBinaryFunc( @@ -2900,26 +2963,23 @@ def gradient(f, *varargs, axis=None, edge_order=1): _MINIMUM_DOCSTRING = """ -Compares two input arrays `x1` and `x2` and returns a new array containing the -element-wise minima. +Computes the minimum value for each element :math:`x1_i` of the input array `x1` +relative to the respective element :math:`x2_i` of the input array `x2`. -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. +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. For full documentation refer to :obj:`numpy.minimum`. Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, expected to have a boolean or numeric data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output).s + Second input array, also expected to have a boolean or numeric data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -2952,6 +3012,13 @@ def gradient(f, *varargs, axis=None, edge_order=1): :obj:`dpnp.max` : The maximum value of an array along a given axis, propagates NaNs. :obj:`dpnp.nanmax` : The maximum value of an array along a given axis, ignores NaNs. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -3022,21 +3089,17 @@ def modf(x1, **kwargs): _MULTIPLY_DOCSTRING = """ -Calculates the product for each element `x1_i` of the input array `x1` with the -respective element `x2_i` of the input array `x2`. +Calculates the product for each element :math:`x1_i` of the input array `x1` +with the respective element :math:`x2_i` of the input array `x2`. For full documentation refer to :obj:`numpy.multiply`. Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, expected to have a boolean or numeric data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also expected to have a boolean or numeric data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -3061,7 +3124,12 @@ def modf(x1, **kwargs): Notes ----- -Equivalent to `x1` * `x2` in terms of array broadcasting. +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + +Equivalent to :math:`x1 * x2` in terms of array broadcasting. Examples -------- @@ -3084,6 +3152,7 @@ def modf(x1, **kwargs): array([[ 0., 1., 4.], [ 0., 4., 10.], [ 0., 7., 16.]]) + """ multiply = DPNPBinaryFunc( @@ -3238,14 +3307,15 @@ def nan_to_num(x, copy=True, nan=0.0, posinf=None, neginf=None): _NEGATIVE_DOCSTRING = """ -Computes the numerical negative for each element `x_i` of input array `x`. +Computes the numerical negative of each element :math:`x_i` (i.e., +:math:`y_i = -x_i`) of the input array `x`. For full documentation refer to :obj:`numpy.negative`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + Input array, expected to have a numeric data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -3284,6 +3354,7 @@ def nan_to_num(x, copy=True, nan=0.0, posinf=None, neginf=None): >>> x = np.array([1., -1.]) >>> -x array([-1., 1.]) + """ negative = DPNPUnaryFunc( @@ -3303,13 +3374,11 @@ def nan_to_num(x, copy=True, nan=0.0, posinf=None, neginf=None): Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - Values to find the next representable value of. - Both inputs `x1` and `x2` can not be scalars at the same time. + Values to find the next representable value of, expected to have a + real-valued floating-point data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - The direction where to look for the next representable value of `x1`. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + The direction where to look for the next representable value of `x1`, + also expected to have a real-valued floating-point data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -3332,6 +3401,13 @@ def nan_to_num(x, copy=True, nan=0.0, posinf=None, neginf=None): Keyword argument `kwargs` is currently unsupported. Otherwise ``NotImplementedError`` exception will be raised. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -3345,6 +3421,7 @@ def nan_to_num(x, copy=True, nan=0.0, posinf=None, neginf=None): >>> c = np.array([eps + 1, 2 - eps]) >>> np.nextafter(a, b) == c array([ True, True]) + """ nextafter = DPNPBinaryFunc( @@ -3358,14 +3435,15 @@ def nan_to_num(x, copy=True, nan=0.0, posinf=None, neginf=None): _POSITIVE_DOCSTRING = """ -Computes the numerical positive for each element `x_i` of input array `x`. +Computes the numerical positive of each element :math:`x_i` (i.e., +:math:`y_i = +x_i`) of the input array `x`. For full documentation refer to :obj:`numpy.positive`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + Input array, expected to have a numeric data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -3408,6 +3486,7 @@ def nan_to_num(x, copy=True, nan=0.0, posinf=None, neginf=None): >>> x = np.array([1., -1.]) >>> +x array([ 1., -1.]) + """ positive = DPNPUnaryFunc( @@ -3420,8 +3499,9 @@ def nan_to_num(x, copy=True, nan=0.0, posinf=None, neginf=None): _POWER_DOCSTRING = """ -Calculates `x1_i` raised to `x2_i` for each element `x1_i` of the input array -`x1` with the respective element `x2_i` of the input array `x2`. +Calculates :math:`x1_i` raised to :math:`x2_i` for each element :math:`x1_i` of +the input array `x1` with the respective element :math:`x2_i` of the input +array `x2`. Note that :obj:`dpnp.pow` is an alias of :obj:`dpnp.power`. @@ -3430,13 +3510,9 @@ def nan_to_num(x, copy=True, nan=0.0, posinf=None, neginf=None): Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, expected to have a numeric data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also expected to have a numeric data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -3467,6 +3543,13 @@ def nan_to_num(x, copy=True, nan=0.0, posinf=None, neginf=None): :obj:`dpnp.fmod` : Calculate the element-wise remainder of division. :obj:`dpnp.float_power` : Power function that promotes integers to floats. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as dp @@ -3500,6 +3583,7 @@ def nan_to_num(x, copy=True, nan=0.0, posinf=None, neginf=None): >>> d = dp.array([-1.0, -4.0]) >>> dp.power(d, 1.5) array([nan, nan]) + """ power = DPNPBinaryFunc( @@ -3620,12 +3704,12 @@ def prod( _PROJ_DOCSTRING = """ -Computes projection of each element `x_i` for input array `x`. +Computes the complex projection of each element :math:`x_i` for input array `x`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + Input array, expected to have a complex floating-point data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -3660,6 +3744,7 @@ def prod( >>> np.proj(np.array([complex(1,np.inf), complex(1,-np.inf), complex(np.inf,-1),])) array([inf+0.j, inf-0.j, inf-0.j]) + """ proj = DPNPUnaryFunc( @@ -3671,14 +3756,15 @@ def prod( _REAL_DOCSTRING = """ -Computes real part of each element `x_i` for input array `x`. +Returns the real component of a complex number for each element :math:`x_i` of +the input array `x`. For full documentation refer to :obj:`numpy.real`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + Input array, expected to have a numeric data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -3719,6 +3805,7 @@ def prod( array([9.+2.j, 8.+4.j, 7.+6.j]) >>> np.real(np.array(1 + 1j)) array(1.) + """ real = DPNPReal( @@ -3794,8 +3881,8 @@ def real_if_close(a, tol=100): _REMAINDER_DOCSTRING = """ -Calculates the remainder of division for each element `x1_i` of the input array -`x1` with the respective element `x2_i` of the input array `x2`. +Calculates the remainder of division for each element :math:`x1_i` of the input +array `x1` with the respective element :math:`x2_i` of the input array `x2`. This function is equivalent to the Python modulus operator. @@ -3804,13 +3891,9 @@ def real_if_close(a, tol=100): Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have a real-valued floating-point data type. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, expected to have a real-valued data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have a real-valued floating-point data type. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also expected to have a real-valued data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -3825,7 +3908,7 @@ def real_if_close(a, tol=100): ------- out : dpnp.ndarray An array containing the element-wise remainders. Each remainder has the - same sign as respective element `x2_i`. The data type of the returned + same sign as respective element :math:`x2_i`. The data type of the returned array is determined by the Type Promotion Rules. Limitations @@ -3839,13 +3922,20 @@ def real_if_close(a, tol=100): :obj:`dpnp.fmod` : Calculate the element-wise remainder of division. :obj:`dpnp.divide` : Standard division. :obj:`dpnp.floor` : Round a number to the nearest integer toward minus infinity. -:obj:`dpnp.floor_divide` : Compute the largest integer smaller or equal to the division of the inputs. +:obj:`dpnp.floor_divide` : Compute the largest integer smaller or equal to the + division of the inputs. :obj:`dpnp.mod` : Calculate the element-wise remainder of division. Notes ----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Returns ``0`` when `x2` is ``0`` and both `x1` and `x2` are (arrays of) integers. + :obj:`dpnp.mod` is an alias of :obj:`dpnp.remainder`. Examples @@ -3863,6 +3953,7 @@ def real_if_close(a, tol=100): >>> x1 = np.arange(7) >>> x1 % 5 array([0, 1, 2, 3, 4, 0, 1]) + """ remainder = DPNPBinaryFunc( @@ -3877,18 +3968,18 @@ def real_if_close(a, tol=100): _RINT_DOCSTRING = """ -Rounds each element `x_i` of the input array `x` to -the nearest integer-valued number. +Rounds each element :math:`x_i` of the input array `x` to the nearest +integer-valued number. -When two integers are equally close to `x_i`, the result is the nearest even -integer to `x_i`. +When two integers are equally close to :math:`x_i`, the result is the nearest +even integer to :math:`x_i`. For full documentation refer to :obj:`numpy.rint`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + Input array, expected to have a numeric data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -3924,6 +4015,7 @@ def real_if_close(a, tol=100): >>> a = np.array([-1.7, -1.5, -0.2, 0.2, 1.5, 1.7, 2.0]) >>> np.rint(a) array([-2., -2., -0., 0., 2., 2., 2.]) + """ @@ -3938,18 +4030,18 @@ def real_if_close(a, tol=100): _ROUND_DOCSTRING = """ -Rounds each element `x_i` of the input array `x` to -the nearest integer-valued number. +Rounds each element :math:`x_i` of the input array `x` to the nearest +integer-valued number. -When two integers are equally close to `x_i`, the result is the nearest even -integer to `x_i`. +When two integers are equally close to :math:`x_i`, the result is the nearest +even integer to :math:`x_i`. For full documentation refer to :obj:`numpy.round`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + Input array, expected to have a numeric data type. decimals : int, optional Number of decimal places to round to (default: 0). If decimals is negative, it specifies the number of positions to the left of the decimal point. @@ -3987,6 +4079,7 @@ def real_if_close(a, tol=100): array([ 1, 2, 3, 11]) >>> np.round(np.array([1, 2, 3, 11]), decimals=-1) array([ 0, 0, 0, 10]) + """ round = DPNPRound( @@ -3999,19 +4092,27 @@ def real_if_close(a, tol=100): ) -_SIGN_DOCSTRING = """ -Computes an indication of the sign of each element `x_i` of input array `x` -using the signum function. +_SIGN_DOCSTRING = r""" +Returns an indication of the sign of a number for each element :math:`x_i` of +the input array `x`. -The signum function returns `-1` if `x_i` is less than `0`, -`0` if `x_i` is equal to `0`, and `1` if `x_i` is greater than `0`. +The sign function (also known as the **signum function**) of a number +:math:`x_i` is defined as + +.. math:: + \operatorname{sign}(x_i) = \begin{cases} + 0 & \textrm{if } x_i = 0 \\ + \frac{x_i}{|x_i|} & \textrm{otherwise} + \end{cases} + + where :math:`|x_i|` is the absolute value of :math:`x_i`. For full documentation refer to :obj:`numpy.sign`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + Input array, expected to have a numeric data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -4048,6 +4149,7 @@ def real_if_close(a, tol=100): array(0) >>> np.sign(np.array(5-2j)) array([1+0j]) + """ sign = DPNPUnaryFunc( @@ -4060,15 +4162,19 @@ def real_if_close(a, tol=100): _SIGNBIT_DOCSTRING = """ -Computes an indication of whether the sign bit of each element `x_i` of -input array `x` is set. +Determines whether the sign bit is set for each element :math:`x_i` of the +input array `x`. + +The sign bit of a real-valued floating-point number :math:`x_i` is set whenever +:math:`x_i` is either ``-0``, less than zero, or a signed ``NaN`` (i.e., a NaN +value whose sign bit is ``1``). For full documentation refer to :obj:`numpy.signbit`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + Input array, expected to have a real-valued floating-point data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -4103,6 +4209,7 @@ def real_if_close(a, tol=100): >>> np.signbit(np.array([1, -2.3, 2.1])) array([False, True, False]) + """ signbit = DPNPUnaryFunc( @@ -4125,7 +4232,7 @@ def real_if_close(a, tol=100): Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have floating-point data type. + Input array, expected to have a floating-point data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -4168,6 +4275,7 @@ def real_if_close(a, tol=100): 0. , 0.08504448, 0.12613779, 0.11643488, 0.06682066, 0. , -0.05846808, -0.08903844, -0.08409186, -0.04923628, 0. ]) + """ sinc = DPNPSinc( @@ -4187,7 +4295,7 @@ def real_if_close(a, tol=100): ---------- x : {dpnp.ndarray, usm_ndarray} The array of values to find the spacing of, expected to have a real-valued - data type. + floating-point data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -4226,6 +4334,7 @@ def real_if_close(a, tol=100): >>> b = np.spacing(a) >>> b == np.finfo(b.dtype).eps array(True) + """ spacing = DPNPUnaryFunc( @@ -4237,21 +4346,17 @@ def real_if_close(a, tol=100): _SUBTRACT_DOCSTRING = """ -Calculates the difference between each element `x1_i` of the input -array `x1` and the respective element `x2_i` of the input array `x2`. +Calculates the difference for each element :math:`x1_i` of the input array `x1` +with the respective element :math:`x2_i` of the input array `x2`. For full documentation refer to :obj:`numpy.subtract`. Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, expected to have a numeric data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also expected to have a numeric data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -4276,7 +4381,12 @@ def real_if_close(a, tol=100): Notes ----- -Equivalent to `x1` - `x2` in terms of array broadcasting. +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + +Equivalent to :math:`x1 - x2` in terms of array broadcasting. Examples -------- @@ -4298,6 +4408,7 @@ def real_if_close(a, tol=100): array([[ 0., 0., 0.], [ 3., 3., 3.], [ 6., 6., 6.]]) + """ subtract = DPNPBinaryFunc( @@ -4544,7 +4655,7 @@ def trapezoid(y, x=None, dx=1.0, axis=-1): _TRUNC_DOCSTRING = """ -Returns the truncated value for each element `x_i` for input array `x`. +Returns the truncated value for each element :math:`x_i` for input array `x`. The truncated value of the scalar `x` is the nearest integer i which is closer to zero than `x` is. In short, the fractional part of the @@ -4553,7 +4664,7 @@ def trapezoid(y, x=None, dx=1.0, axis=-1): Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have a real-valued floating-point data type. + Input array, expected to have a boolean or real-valued data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -4589,6 +4700,7 @@ def trapezoid(y, x=None, dx=1.0, axis=-1): >>> a = np.array([-1.7, -1.5, -0.2, 0.2, 1.5, 1.7, 2.0]) >>> np.trunc(a) array([-1.0, -1.0, -0.0, 0.0, 1.0, 1.0, 2.0]) + """ trunc = DPNPUnaryFunc( From ae17868c7b02486e8d51122ee046a54f4b6758f2 Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Wed, 9 Apr 2025 15:16:35 +0200 Subject: [PATCH 30/32] Rephrase a case when an input array may have any dtype --- dpnp/dpnp_iface_logic.py | 52 ++++++++++++++++---------------- dpnp/dpnp_iface_mathematical.py | 32 ++++++++++---------- dpnp/dpnp_iface_trigonometric.py | 2 +- 3 files changed, 43 insertions(+), 43 deletions(-) diff --git a/dpnp/dpnp_iface_logic.py b/dpnp/dpnp_iface_logic.py index a91e7a420c76..1e1ea964915f 100644 --- a/dpnp/dpnp_iface_logic.py +++ b/dpnp/dpnp_iface_logic.py @@ -195,9 +195,9 @@ def allclose(a, b, rtol=1.0e-5, atol=1.0e-8, equal_nan=False): Parameters ---------- a : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have numeric data type. + First input array, expected to have a numeric data type. b : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have numeric data type. + Second input array, also expected to have a numeric data type. rtol : {dpnp.ndarray, usm_ndarray, scalar}, optional The relative tolerance parameter. @@ -552,9 +552,9 @@ def array_equiv(a1, a2): Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have a boolean or numeric data type. + First input array, may have any data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have a boolean or numeric data type. + Second input array, also may have any data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array have the correct shape and the expected data type. @@ -632,9 +632,9 @@ def array_equiv(a1, a2): Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have a boolean or numeric data type. + First input array, may have any data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have a boolean or numeric data type. + Second input array, also may have any data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -706,9 +706,9 @@ def array_equiv(a1, a2): Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have a boolean or numeric data type. + First input array, may have any data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have a boolean or numeric data type. + Second input array, also may have any data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -790,9 +790,9 @@ def isclose(a, b, rtol=1e-05, atol=1e-08, equal_nan=False): Parameters ---------- a : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have numeric data type. + First input array, expected to have a numeric data type. b : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have numeric data type. + Second input array, also expected to have a numeric data type. rtol : {dpnp.ndarray, usm_ndarray, scalar}, optional The relative tolerance parameter. @@ -992,7 +992,7 @@ def iscomplexobj(x): Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have a boolean or numeric data type. + Input array, may have any data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -1124,7 +1124,7 @@ def isfortran(a): Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have a boolean or numeric data type. + Input array, may have any data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -1182,7 +1182,7 @@ def isfortran(a): Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have a boolean or numeric data type. + Input array, may have any data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -1517,9 +1517,9 @@ def isscalar(element): Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have a boolean or numeric data type. + First input array, may have any data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have a boolean or numeric data type. + Second input array, also may have any data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -1591,9 +1591,9 @@ def isscalar(element): Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have a boolean or numeric data type. + First input array, may have any data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have a boolean or numeric data type. + Second input array, also may have any data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -1664,9 +1664,9 @@ def isscalar(element): Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have a boolean or numeric data type. + First input array, may have any data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have a boolean or numeric data type. + Second input array, also may have any data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -1739,7 +1739,7 @@ def isscalar(element): Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have a boolean or numeric data type. + Input array, may have any data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -1803,9 +1803,9 @@ def isscalar(element): Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have a boolean or numeric data type. + First input array, may have any data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have a boolean or numeric data type. + Second input array, also may have any data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -1879,9 +1879,9 @@ def isscalar(element): Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have a boolean or numeric data type. + First input array, may have any data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have a boolean or numeric data type. + Second input array, also may have any data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -1953,9 +1953,9 @@ def isscalar(element): Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have a boolean or numeric data type. + First input array, may have any data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have a boolean or numeric data type. + Second input array, also may have any data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. diff --git a/dpnp/dpnp_iface_mathematical.py b/dpnp/dpnp_iface_mathematical.py index f65fdf16f8c4..192750adcddf 100644 --- a/dpnp/dpnp_iface_mathematical.py +++ b/dpnp/dpnp_iface_mathematical.py @@ -356,7 +356,7 @@ def _process_ediff1d_args(arg, arg_name, ary_dtype, ary_sycl_queue, usm_type): Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have a boolean or numeric data type. + Input array, may have any data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -426,9 +426,9 @@ def _process_ediff1d_args(arg, arg_name, ary_dtype, ary_sycl_queue, usm_type): Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have a boolean or numeric data type. + First input array, may have any data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have a boolean or numeric data type. + Second input array, also may have any data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -573,7 +573,7 @@ def around(x, /, decimals=0, out=None): Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + Input array, expected to have a numeric data type. decimals : int, optional Number of decimal places to round to. If `decimals` is negative, it specifies the number of positions to the left of the decimal point. @@ -758,7 +758,7 @@ def clip(a, /, min=None, max=None, *, out=None, order="K", **kwargs): Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have a boolean or numeric data type. + Input array, may have any data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -2050,9 +2050,9 @@ def ediff1d(ary, to_end=None, to_begin=None): Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have a boolean or numeric data type. + First input array, may have any data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have a boolean or numeric data type. + Second input array, also may have any data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -2141,9 +2141,9 @@ def ediff1d(ary, to_end=None, to_begin=None): Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have a boolean or numeric data type. + First input array, may have any data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have a boolean or numeric data type. + Second input array, also may have any data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -2688,7 +2688,7 @@ def gradient(f, *varargs, axis=None, edge_order=1): Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have a boolean or numeric data type. + Input array, may have any data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -2888,9 +2888,9 @@ def gradient(f, *varargs, axis=None, edge_order=1): Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have a boolean or numeric data type. + First input array, may have any data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have a boolean or numeric data type. + Second input array, also may have any data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -2977,9 +2977,9 @@ def gradient(f, *varargs, axis=None, edge_order=1): Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have a boolean or numeric data type. + First input array, may have any data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have a boolean or numeric data type. + Second input array, also may have any data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -3097,9 +3097,9 @@ def modf(x1, **kwargs): Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have a boolean or numeric data type. + First input array, may have any data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have a boolean or numeric data type. + Second input array, also may have any data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. diff --git a/dpnp/dpnp_iface_trigonometric.py b/dpnp/dpnp_iface_trigonometric.py index 60697267720e..9e7bf33b1fac 100644 --- a/dpnp/dpnp_iface_trigonometric.py +++ b/dpnp/dpnp_iface_trigonometric.py @@ -2447,7 +2447,7 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have a boolean or numeric data type. + Input array, may have any data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. From 5f342126cb9cd79f1fb55c9966315370aaa41f85 Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Thu, 10 Apr 2025 13:25:23 +0200 Subject: [PATCH 31/32] Apply review comments --- dpnp/dpnp_iface_linearalgebra.py | 6 +++--- dpnp/dpnp_iface_logic.py | 2 +- dpnp/dpnp_iface_mathematical.py | 30 +++++++++++++++--------------- dpnp/dpnp_iface_trigonometric.py | 20 ++++++++++---------- 4 files changed, 29 insertions(+), 29 deletions(-) diff --git a/dpnp/dpnp_iface_linearalgebra.py b/dpnp/dpnp_iface_linearalgebra.py index c881edfd4c35..fa2cb6136d67 100644 --- a/dpnp/dpnp_iface_linearalgebra.py +++ b/dpnp/dpnp_iface_linearalgebra.py @@ -617,7 +617,7 @@ def inner(a, b): See Also -------- - :obj:`dpnp.einsum` : Einstein summation convention.. + :obj:`dpnp.einsum` : Einstein summation convention. :obj:`dpnp.dot` : Generalized matrix product, using second last dimension of `b`. :obj:`dpnp.tensordot` : Sum products over arbitrary axes. @@ -998,7 +998,7 @@ def matvec( See Also -------- - :obj:`dpnp.vecdot` : Vector-vector product.. + :obj:`dpnp.vecdot` : Vector-vector product. :obj:`dpnp.vecmat` : Vector-matrix product. :obj:`dpnp.matmul` : Matrix-matrix product. :obj:`dpnp.einsum` : Einstein summation convention. @@ -1502,7 +1502,7 @@ def vecmat( See Also -------- - :obj:`dpnp.vecdot` : Vector-vector product.. + :obj:`dpnp.vecdot` : Vector-vector product. :obj:`dpnp.matvec` : Matrix-vector product. :obj:`dpnp.matmul` : Matrix-matrix product. :obj:`dpnp.einsum` : Einstein summation convention. diff --git a/dpnp/dpnp_iface_logic.py b/dpnp/dpnp_iface_logic.py index 1e1ea964915f..84258f698b8f 100644 --- a/dpnp/dpnp_iface_logic.py +++ b/dpnp/dpnp_iface_logic.py @@ -985,7 +985,7 @@ def iscomplexobj(x): _ISFINITE_DOCSTRING = """ -Test each element :math:`x_i` of input array `x` if finite. +Test each element :math:`x_i` of the input array `x` to determine if finite. For full documentation refer to :obj:`numpy.isfinite`. diff --git a/dpnp/dpnp_iface_mathematical.py b/dpnp/dpnp_iface_mathematical.py index 192750adcddf..7c8731c068f8 100644 --- a/dpnp/dpnp_iface_mathematical.py +++ b/dpnp/dpnp_iface_mathematical.py @@ -351,7 +351,7 @@ def _process_ediff1d_args(arg, arg_name, ary_dtype, ary_sycl_queue, usm_type): _ABS_DOCSTRING = """ Calculates the absolute value for each element :math:`x_i` of input array `x`. -For full documentation refer to :obj:`numpy.abs`. +For full documentation refer to :obj:`numpy.absolute`. Parameters ---------- @@ -372,8 +372,8 @@ def _process_ediff1d_args(arg, arg_name, ary_dtype, ary_sycl_queue, usm_type): out : dpnp.ndarray An array containing the element-wise absolute values. For complex input, the absolute value is its magnitude. - If `x` has a real-valued floating-point data type, the returned array has - the same data type as `x`. If `x` has a complex floating-point data type, + If `x` has a real-valued data type, the returned array has the + same data type as `x`. If `x` has a complex floating-point data type, the returned array has a real-valued floating-point data type whose precision matches the precision of `x`. @@ -389,7 +389,7 @@ def _process_ediff1d_args(arg, arg_name, ary_dtype, ary_sycl_queue, usm_type): Notes ----- -``dpnp.absolute`` is a shorthand for this function. +``dpnp.absolute`` is an equivalent function. Examples -------- @@ -497,7 +497,7 @@ def _process_ediff1d_args(arg, arg_name, ary_dtype, ary_sycl_queue, usm_type): ) -_ANGLE_DOCSTRING = """ +_ANGLE_DOCSTRING = r""" Computes the phase angle (also called the argument) of each element :math:`x_i` for input array `x`. @@ -530,13 +530,13 @@ def _process_ediff1d_args(arg, arg_name, ary_dtype, ary_sycl_queue, usm_type): Notes ----- -Although the angle of the complex number 0 is undefined, `dpnp.angle(0)` returns -the value ``0``. +Although the angle of the complex number ``0`` is undefined, ``dpnp.angle(0)`` +returns the value ``0``. See Also -------- -:obj:`dpnp.atan2` : Element-wise arc tangent of `x1/x2` choosing the quadrant - correctly. +:obj:`dpnp.atan2` : Element-wise arc tangent of :math:`\frac{x1}/{x2}` choosing + the quadrant correctly. :obj:`dpnp.atan` : Trigonometric inverse tangent, element-wise. :obj:`dpnp.abs` : Calculate the absolute value element-wise. :obj:`dpnp.real` : Return the real part of the complex argument. @@ -2703,7 +2703,7 @@ def gradient(f, *varargs, axis=None, edge_order=1): ------- out : dpnp.ndarray An array containing the element-wise imaginary component of input. - If the input is a real-valued floating-point data type, the returned array has + If the input is a real-valued data type, the returned array has the same data type. If the input is a complex floating-point data type, the returned array has a floating-point data type with the same floating-point precision as complex input. @@ -3764,7 +3764,7 @@ def prod( Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have a numeric data type. + Input array, may have any data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -3779,7 +3779,7 @@ def prod( ------- out : dpnp.ndarray An array containing the element-wise real component of input. - If the input is a real-valued floating-point data type, the returned array has + If the input is a real-valued data type, the returned array has the same data type. If the input is a complex floating-point data type, the returned array has a floating-point data type with the same floating-point precision as complex input. @@ -4105,7 +4105,7 @@ def real_if_close(a, tol=100): \frac{x_i}{|x_i|} & \textrm{otherwise} \end{cases} - where :math:`|x_i|` is the absolute value of :math:`x_i`. +where :math:`|x_i|` is the absolute value of :math:`x_i`. For full documentation refer to :obj:`numpy.sign`. @@ -4166,8 +4166,8 @@ def real_if_close(a, tol=100): input array `x`. The sign bit of a real-valued floating-point number :math:`x_i` is set whenever -:math:`x_i` is either ``-0``, less than zero, or a signed ``NaN`` (i.e., a NaN -value whose sign bit is ``1``). +:math:`x_i` is either ``-0``, less than zero, or a signed ``NaN`` +(i.e., a ``NaN`` value whose sign bit is ``1``). For full documentation refer to :obj:`numpy.signbit`. diff --git a/dpnp/dpnp_iface_trigonometric.py b/dpnp/dpnp_iface_trigonometric.py index 9e7bf33b1fac..9840bd3f418d 100644 --- a/dpnp/dpnp_iface_trigonometric.py +++ b/dpnp/dpnp_iface_trigonometric.py @@ -315,7 +315,7 @@ def _get_accumulation_res_dt(a, dtype): :obj:`dpnp.acos` : Trigonometric inverse cosine, element-wise. :obj:`dpnp.tan` : Trigonometric tangent, element-wise. :obj:`dpnp.atan` : Trigonometric inverse tangent, element-wise. -:obj:`dpnp.atan2` : Element-wise arc tangent of `x1/x2` +:obj:`dpnp.atan2` : Element-wise arc tangent of :math:`\frac{x1}/{x2}` choosing the quadrant correctly. :obj:`dpnp.asinh` : Hyperbolic inverse sine, element-wise. @@ -477,7 +477,7 @@ def _get_accumulation_res_dt(a, dtype): See Also -------- -:obj:`dpnp.atan2` : Element-wise arc tangent of `x1/x2` +:obj:`dpnp.atan2` : Element-wise arc tangent of :math:`\frac{x1}/{x2}` choosing the quadrant correctly. :obj:`dpnp.angle` : Argument of complex values. :obj:`dpnp.tan` : Trigonometric tangent, element-wise. @@ -554,9 +554,9 @@ def _get_accumulation_res_dt(a, dtype): Returns ------- out : dpnp.ndarray - An array containing the inverse tangent of the quotient :math:`x1/x2`, in - radians. The returned array must have a real-valued floating-point data - type determined by Type Promotion Rules. + An array containing the inverse tangent of the quotient + :math:`\frac{x1}/{x2}`, in radians. The returned array must have a + real-valued floating-point data type determined by Type Promotion Rules. Limitations ----------- @@ -1027,7 +1027,7 @@ def cumlogsumexp( _DEGREES_DOCSTRING = r""" -Convert angles from degrees to radians for each element :math:`x_i` for input +Convert angles from radian to degrees for each element :math:`x_i` for input array `x`. For full documentation refer to :obj:`numpy.degrees`. @@ -1210,8 +1210,8 @@ def cumlogsumexp( _EXPM1_DOCSTRING = r""" -Computes the exponential minus 1 for each element :math:`x_i` of input array -`x`. +Computes the exponential minus ``1`` for each element :math:`x_i` of input +array `x`. For full documentation refer to :obj:`numpy.expm1`. @@ -1918,7 +1918,7 @@ def logsumexp(x, /, *, axis=None, dtype=None, keepdims=False, out=None): _RAD2DEG_DOCSTRING = r""" -Convert angles from degrees to radians for each element :math:`x_i` for input +Convert angles from radians to degrees for each element :math:`x_i` for input array `x`. For full documentation refer to :obj:`numpy.rad2deg`. @@ -2472,7 +2472,7 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): See Also -------- -:obj:`dpnp..linalg.matrix_power` : Raise a square matrix to the (integer) +:obj:`dpnp.linalg.matrix_power` : Raise a square matrix to the (integer) power `n`. :obj:`dpnp.sqrt` : Calculate :math:`\sqrt{x}`, element-wise. :obj:`dpnp.power` : Calculate :math:`{x1}^{x2}`, element-wise. From 0cb520bcab42af15c83b6a2a6a71c8a31835307c Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Thu, 10 Apr 2025 15:34:12 +0200 Subject: [PATCH 32/32] Update atan2 docstring with proper use of :math:`\frac{x1}{x2}` --- dpnp/dpnp_iface_mathematical.py | 2 +- dpnp/dpnp_iface_trigonometric.py | 12 ++++++------ 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/dpnp/dpnp_iface_mathematical.py b/dpnp/dpnp_iface_mathematical.py index 11f96ae04cce..3613c9bffff6 100644 --- a/dpnp/dpnp_iface_mathematical.py +++ b/dpnp/dpnp_iface_mathematical.py @@ -535,7 +535,7 @@ def _process_ediff1d_args(arg, arg_name, ary_dtype, ary_sycl_queue, usm_type): See Also -------- -:obj:`dpnp.atan2` : Element-wise arc tangent of :math:`\frac{x1}/{x2}` choosing +:obj:`dpnp.atan2` : Element-wise arc tangent of :math:`\frac{x1}{x2}` choosing the quadrant correctly. :obj:`dpnp.atan` : Trigonometric inverse tangent, element-wise. :obj:`dpnp.abs` : Calculate the absolute value element-wise. diff --git a/dpnp/dpnp_iface_trigonometric.py b/dpnp/dpnp_iface_trigonometric.py index 9840bd3f418d..fff45f92f96b 100644 --- a/dpnp/dpnp_iface_trigonometric.py +++ b/dpnp/dpnp_iface_trigonometric.py @@ -315,7 +315,7 @@ def _get_accumulation_res_dt(a, dtype): :obj:`dpnp.acos` : Trigonometric inverse cosine, element-wise. :obj:`dpnp.tan` : Trigonometric tangent, element-wise. :obj:`dpnp.atan` : Trigonometric inverse tangent, element-wise. -:obj:`dpnp.atan2` : Element-wise arc tangent of :math:`\frac{x1}/{x2}` +:obj:`dpnp.atan2` : Element-wise arc tangent of :math:`\frac{x1}{x2}` choosing the quadrant correctly. :obj:`dpnp.asinh` : Hyperbolic inverse sine, element-wise. @@ -477,7 +477,7 @@ def _get_accumulation_res_dt(a, dtype): See Also -------- -:obj:`dpnp.atan2` : Element-wise arc tangent of :math:`\frac{x1}/{x2}` +:obj:`dpnp.atan2` : Element-wise arc tangent of :math:`\frac{x1}{x2}` choosing the quadrant correctly. :obj:`dpnp.angle` : Argument of complex values. :obj:`dpnp.tan` : Trigonometric tangent, element-wise. @@ -523,9 +523,9 @@ def _get_accumulation_res_dt(a, dtype): arctan = atan # arctan is an alias for atan -_ATAN2_DOCSTRING = """ -Calculates the inverse tangent of the quotient :math:`x1_i/x2_i` for each -element :math:`x1_i` of the input array `x1` with the respective element +_ATAN2_DOCSTRING = r""" +Calculates the inverse tangent of the quotient :math:`\frac{x1_i}{x2_i}` for +each element :math:`x1_i` of the input array `x1` with the respective element :math:`x2_i` of the input array `x2`. Note that :obj:`dpnp.arctan2` is an alias of :obj:`dpnp.atan2`. @@ -555,7 +555,7 @@ def _get_accumulation_res_dt(a, dtype): ------- out : dpnp.ndarray An array containing the inverse tangent of the quotient - :math:`\frac{x1}/{x2}`, in radians. The returned array must have a + :math:`\frac{x1}{x2}`, in radians. The returned array must have a real-valued floating-point data type determined by Type Promotion Rules. Limitations