From ec5fff49309f9d9a0c2b9853781871ce261ba094 Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Wed, 2 Apr 2025 19:03:18 +0200 Subject: [PATCH 1/2] Correct expected data types of input arrays in docstrings of element-wise functions --- dpctl/tensor/_elementwise_funcs.py | 129 +++++++++++++++-------------- 1 file changed, 67 insertions(+), 62 deletions(-) diff --git a/dpctl/tensor/_elementwise_funcs.py b/dpctl/tensor/_elementwise_funcs.py index 4731ec8631..8d5c4023b2 100644 --- a/dpctl/tensor/_elementwise_funcs.py +++ b/dpctl/tensor/_elementwise_funcs.py @@ -33,7 +33,7 @@ Args: x (usm_ndarray): - Input array. + Input array, expected to have a boolean or numeric data type. out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. @@ -75,8 +75,8 @@ Returns: usm_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. + and in the closed interval :math:`[0, \pi]`. The data type of the + returned array is determined by the Type Promotion Rules. """ acos = UnaryElementwiseFunc( @@ -104,8 +104,8 @@ Returns: usm_ndarray: An array containing the element-wise inverse hyperbolic cosine, in - radians and in the half-closed interval `[0, inf)`. The data type - of the returned array is determined by the Type Promotion Rules. + radians and in the half-closed interval :math:`[0, \infty)`. The data + type of the returned array is determined by the Type Promotion Rules. """ acosh = UnaryElementwiseFunc( @@ -123,9 +123,9 @@ Args: x1 (usm_ndarray): - First input array. + First input array, expected to have a boolean or numeric data type. x2 (usm_ndarray): - Second input array. + Second input array, expected to have a boolean or numeric data type. out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. @@ -168,7 +168,7 @@ Returns: usm_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 :math:`[-\pi/2, \pi/2]`. The data type of the returned array is determined by the Type Promotion Rules. """ @@ -196,8 +196,8 @@ Returns: usm_ndarray: - An array containing the element-wise inverse hyperbolic sine. - The data type of the returned array is determined by + 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. """ @@ -226,7 +226,7 @@ Returns: usm_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 :math:`[-\pi/2, \pi/2]`. The data type of the returned array is determined by the Type Promotion Rules. """ @@ -289,8 +289,8 @@ Returns: usm_ndarray: - An array containing the element-wise hyperbolic inverse tangent. - The data type of the returned array is determined by + An array containing the element-wise hyperbolic inverse tangent, in + radians. The data type of the returned array is determined by the Type Promotion Rules. """ @@ -555,7 +555,7 @@ Args: x (usm_ndarray): - Input array, expected to have a numeric data type. + Input array, expected to have a boolean or numeric data type. out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. @@ -674,9 +674,10 @@ Args: x1 (usm_ndarray): - First input array. + First input array, expected to have a boolean or numeric data type. x2 (usm_ndarray): - Second input array. + Second input array, also expected to have a boolean or numeric data + type. out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. @@ -719,7 +720,7 @@ Returns: usm_ndarray: - An array containing the element-wise exponential of x. + An array containing the element-wise exponential of `x`. The data type of the returned array is determined by the Type Promotion Rules. """ @@ -796,10 +797,9 @@ Args: x1 (usm_ndarray): - First input array, expected to have a real-valued or boolean data type. + First input array, expected to have a real-valued data type. x2 (usm_ndarray): - Second input array, also expected to have a real-valued or boolean data - type. + Second input array, also expected to have a real-valued data type. out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. @@ -833,9 +833,10 @@ Args: x1 (usm_ndarray): - First input array. + First input array, expected to have a boolean or numeric data type. x2 (usm_ndarray): - Second input array. + Second input array, also expected to have a boolean or numeric data + type. out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. @@ -868,9 +869,10 @@ Args: x1 (usm_ndarray): - First input array. + First input array, expected to have a boolean or numeric data type. x2 (usm_ndarray): - Second input array. + Second input array, also expected to have a boolean or numeric data + type. out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. @@ -903,7 +905,7 @@ Args: x (usm_ndarray): - Input array. + Input array, expected to have a boolean or numeric data type. out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. @@ -934,7 +936,7 @@ Args: x (usm_ndarray): - Input array. + Input array, expected to have a boolean or numeric data type. out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. @@ -963,7 +965,7 @@ Args: x (usm_ndarray): - Input array. + Input array, expected to have a boolean or numeric data type. out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. @@ -991,7 +993,7 @@ Args: x (usm_ndarray): - Input array. + Input array, expected to have a boolean or numeric data type. out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. @@ -1020,9 +1022,9 @@ Args: x1 (usm_ndarray): - First input array. + First input array, expected to have a boolean or numeric data type. x2 (usm_ndarray): - Second input array. + Second input array, expected to have a boolean or numeric data type. out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. @@ -1056,9 +1058,9 @@ Args: x1 (usm_ndarray): - First input array. + First input array, expected to have a boolean or numeric data type. x2 (usm_ndarray): - Second input array. + Second input array, expected to have a boolean or numeric data type. out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. @@ -1242,9 +1244,9 @@ Args: x1 (usm_ndarray): - First input array. + First input array, expected to have a boolean or numeric data type. x2 (usm_ndarray): - Second input array. + Second input array, expected to have a boolean or numeric data type. out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. @@ -1273,7 +1275,7 @@ Args: x (usm_ndarray): - Input array. + Input array, expected to have a boolean or numeric data type. out (usm_ndarray): Output array to populate. Array must have the correct shape and the expected data type. @@ -1303,9 +1305,9 @@ Args: x1 (usm_ndarray): - First input array. + First input array, expected to have a boolean or numeric data type. x2 (usm_ndarray): - Second input array. + Second input array, expected to have a boolean or numeric data type. out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. @@ -1335,9 +1337,9 @@ Args: x1 (usm_ndarray): - First input array. + First input array, expected to have a boolean or numeric data type. x2 (usm_ndarray): - Second input array. + Second input array, expected to have a boolean or numeric data type. out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. @@ -1367,9 +1369,9 @@ Args: x1 (usm_ndarray): - First input array. + First input array, expected to have a boolean or numeric data type. x2 (usm_ndarray): - Second input array. + Second input array, expected to have a boolean or numeric data type. out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. @@ -1400,9 +1402,9 @@ Args: x1 (usm_ndarray): - First input array. + First input array, expected to have a boolean or numeric data type. x2 (usm_ndarray): - Second input array. + Second input array, expected to have a boolean or numeric data type. out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. @@ -1433,9 +1435,9 @@ Args: x1 (usm_ndarray): - First input array. + First input array, expected to have a boolean or numeric data type. x2 (usm_ndarray): - Second input array. + Second input array, expected to have a boolean or numeric data type. out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. @@ -1497,9 +1499,11 @@ Args: x1 (usm_ndarray): - First input array. + First input array, expected to have a real-valued floating-point data + type. x2 (usm_ndarray): - Second input array. + Second input array, expected to have a real-valued floating-point data + type. out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. @@ -1652,7 +1656,7 @@ Args: x (usm_ndarray): - Input array. + Input array, expected to have a numeric data type. out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. @@ -1724,7 +1728,7 @@ Args: x (usm_ndarray): - Input array, expected to have a real-valued data type. + Input array, expected to have a numeric data type. out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. @@ -1813,7 +1817,7 @@ Args: x (usm_ndarray): - Input array, expected to have a floating-point data type. + Input array, expected to have a real-valued floating-point data type. out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. @@ -1867,7 +1871,7 @@ Args: x (usm_ndarray): - Input array, expected to have numeric data type. + Input array, expected to have a boolean or numeric data type. out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. @@ -2041,8 +2045,8 @@ _hypot_docstring_ = r""" hypot(x1, x2, /, \*, out=None, order='K') -Calculates the hypotenuse for a right triangle with "legs" `x1_i` and `x2_i` of -input arrays `x1` and `x2`. +Computes the square root of the sum of squares for each element `x1_i` of the +input array `x1` with the respective element `x2_i` of the input array `x2`. Args: x1 (usm_ndarray): @@ -2075,11 +2079,11 @@ _cbrt_docstring_ = r""" cbrt(x, /, \*, out=None, order='K') -Computes positive cube-root for each element `x_i` for input array `x`. +Computes the cube-root for each element `x_i` for input array `x`. Args: x (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 (Union[usm_ndarray, None], optional): Output array to populate. Array have the correct shape and the expected data type. @@ -2090,7 +2094,7 @@ Returns: usm_ndarray: - An array containing the element-wise positive cube-root. + An array containing the element-wise cube-root. The data type of the returned array is determined by the Type Promotion Rules. """ @@ -2140,10 +2144,11 @@ Args: x1 (usm_ndarray): - First input array, expected to have a real floating-point data type. - x2 (usm_ndarray): - Second input array, also expected to have a real floating-point data + First input array, expected to have a real-valued floating-point data type. + x2 (usm_ndarray): + Second input array, also expected to have a real-valued floating-point + data type. out (Union[usm_ndarray, None], optional): Output array to populate. Array have the correct shape and the expected data type. @@ -2174,7 +2179,7 @@ Args: x (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 (Union[usm_ndarray, None], optional): Output array to populate. Array have the correct shape and the expected data type. @@ -2204,7 +2209,7 @@ Args: x (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 (Union[usm_ndarray, None], optional): Output array to populate. Array have the correct shape and the expected data type. @@ -2239,7 +2244,7 @@ Args: x (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. out (Union[usm_ndarray, None], optional): Output array to populate. Array have the correct shape and the expected data type. From c138cea00128df1beb1e09e5626e2d7214cccba2 Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Wed, 9 Apr 2025 11:42:45 +0200 Subject: [PATCH 2/2] Rephrase a case when an input array may have any dtype --- dpctl/tensor/_elementwise_funcs.py | 67 ++++++++++++++---------------- 1 file changed, 32 insertions(+), 35 deletions(-) diff --git a/dpctl/tensor/_elementwise_funcs.py b/dpctl/tensor/_elementwise_funcs.py index 8d5c4023b2..e91cc9740d 100644 --- a/dpctl/tensor/_elementwise_funcs.py +++ b/dpctl/tensor/_elementwise_funcs.py @@ -33,7 +33,7 @@ Args: x (usm_ndarray): - Input array, expected to have a boolean or numeric data type. + Input array. May have any data type. out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. @@ -123,9 +123,9 @@ Args: x1 (usm_ndarray): - First input array, expected to have a boolean or numeric data type. + First input array. May have any data type. x2 (usm_ndarray): - Second input array, expected to have a boolean or numeric data type. + Second input array. May have any data type. out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. @@ -555,7 +555,7 @@ Args: x (usm_ndarray): - Input array, expected to have a boolean or numeric data type. + Input array. May have any data type. out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. @@ -674,10 +674,9 @@ Args: x1 (usm_ndarray): - First input array, expected to have a boolean or numeric data type. + First input array. May have any data type. x2 (usm_ndarray): - Second input array, also expected to have a boolean or numeric data - type. + Second input array. May have any data type. out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. @@ -833,10 +832,9 @@ Args: x1 (usm_ndarray): - First input array, expected to have a boolean or numeric data type. + First input array. May have any data type. x2 (usm_ndarray): - Second input array, also expected to have a boolean or numeric data - type. + Second input array. May have any data type. out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. @@ -869,10 +867,9 @@ Args: x1 (usm_ndarray): - First input array, expected to have a boolean or numeric data type. + First input array. May have any data type. x2 (usm_ndarray): - Second input array, also expected to have a boolean or numeric data - type. + Second input array. May have any data type. out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. @@ -905,7 +902,7 @@ Args: x (usm_ndarray): - Input array, expected to have a boolean or numeric data type. + Input array. May have any data type. out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. @@ -936,7 +933,7 @@ Args: x (usm_ndarray): - Input array, expected to have a boolean or numeric data type. + Input array. May have any data type. out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. @@ -965,7 +962,7 @@ Args: x (usm_ndarray): - Input array, expected to have a boolean or numeric data type. + Input array. May have any data type. out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. @@ -993,7 +990,7 @@ Args: x (usm_ndarray): - Input array, expected to have a boolean or numeric data type. + Input array. May have any data type. out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. @@ -1022,9 +1019,9 @@ Args: x1 (usm_ndarray): - First input array, expected to have a boolean or numeric data type. + First input array. May have any data type. x2 (usm_ndarray): - Second input array, expected to have a boolean or numeric data type. + Second input array. May have any data type. out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. @@ -1058,9 +1055,9 @@ Args: x1 (usm_ndarray): - First input array, expected to have a boolean or numeric data type. + First input array. May have any data type. x2 (usm_ndarray): - Second input array, expected to have a boolean or numeric data type. + Second input array. May have any data type. out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. @@ -1244,9 +1241,9 @@ Args: x1 (usm_ndarray): - First input array, expected to have a boolean or numeric data type. + First input array. May have any data type. x2 (usm_ndarray): - Second input array, expected to have a boolean or numeric data type. + Second input array. May have any data type. out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. @@ -1275,7 +1272,7 @@ Args: x (usm_ndarray): - Input array, expected to have a boolean or numeric data type. + Input array. May have any data type. out (usm_ndarray): Output array to populate. Array must have the correct shape and the expected data type. @@ -1305,9 +1302,9 @@ Args: x1 (usm_ndarray): - First input array, expected to have a boolean or numeric data type. + First input array. May have any data type. x2 (usm_ndarray): - Second input array, expected to have a boolean or numeric data type. + Second input array. May have any data type. out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. @@ -1337,9 +1334,9 @@ Args: x1 (usm_ndarray): - First input array, expected to have a boolean or numeric data type. + First input array. May have any data type. x2 (usm_ndarray): - Second input array, expected to have a boolean or numeric data type. + Second input array. May have any data type. out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. @@ -1369,9 +1366,9 @@ Args: x1 (usm_ndarray): - First input array, expected to have a boolean or numeric data type. + First input array. May have any data type. x2 (usm_ndarray): - Second input array, expected to have a boolean or numeric data type. + Second input array. May have any data type. out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. @@ -1402,9 +1399,9 @@ Args: x1 (usm_ndarray): - First input array, expected to have a boolean or numeric data type. + First input array. May have any data type. x2 (usm_ndarray): - Second input array, expected to have a boolean or numeric data type. + Second input array. May have any data type. out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. @@ -1435,9 +1432,9 @@ Args: x1 (usm_ndarray): - First input array, expected to have a boolean or numeric data type. + First input array. May have any data type. x2 (usm_ndarray): - Second input array, expected to have a boolean or numeric data type. + Second input array. May have any data type. out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. @@ -1871,7 +1868,7 @@ Args: x (usm_ndarray): - Input array, expected to have a boolean or numeric data type. + Input array. May have any data type. out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type.