Update doc of elementwise functions (#2188)

* Update bitwise docs adding broadcast info

* Update logic func docs adding broadcast info

* Update mathematical func docs adding broadcast info

* Update trigonometric func docs adding broadcast info

Author: vlad-perevezentsev

dpnp/dpnp_iface_bitwise.py

@@ -140,6 +140,8 @@ def binary_repr(num, width=None):
 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).
 out : {None, dpnp.ndarray, usm_ndarray}, optional
     Output array to populate.
     Array must have the correct shape and the expected data type.
@@ -224,6 +226,8 @@ def binary_repr(num, width=None):
 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).
 out : {None, dpnp.ndarray, usm_ndarray}, optional
     Output array to populate.
     Array must have the correct shape and the expected data type.
@@ -299,6 +303,8 @@ def binary_repr(num, width=None):
 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).
 out : {None, dpnp.ndarray, usm_ndarray}, optional
     Output array to populate.
     Array must have the correct shape and the expected data type.
@@ -458,6 +464,8 @@ def binary_repr(num, width=None):
     Second input array, also expected to have 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.
@@ -532,6 +540,8 @@ def binary_repr(num, width=None):
     Second input array, also expected to have 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.

dpnp/dpnp_iface_logic.py

@@ -199,9 +199,11 @@ def allclose(a, b, rtol=1.0e-5, atol=1.0e-8, equal_nan=False):
         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. Default: ``1e-05``.
+        The relative tolerance parameter.
+        Default: ``1e-05``.
     atol : {dpnp.ndarray, usm_ndarray, scalar}, optional
-        The absolute tolerance parameter. Default: ``1e-08``.
+        The absolute tolerance parameter.
+        Default: ``1e-08``.
     equal_nan : bool
         Whether to compare ``NaNs`` as equal. If ``True``, ``NaNs`` in `a` will
         be considered equal to ``NaNs`` in `b` in the output array.
@@ -213,14 +215,20 @@ def allclose(a, b, rtol=1.0e-5, atol=1.0e-8, equal_nan=False):
         A 0-dim array with ``True`` value if the two arrays are equal within
         the given tolerance; with ``False`` otherwise.
 
-
     See Also
     --------
     :obj:`dpnp.isclose` : Test whether two arrays are element-wise equal.
     :obj:`dpnp.all` : Test whether all elements evaluate to True.
     :obj:`dpnp.any` : Test whether any element evaluates to True.
     :obj:`dpnp.equal` : Return (x1 == x2) element-wise.
 
+    Notes
+    -----
+    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``.
+    The same is true for :obj:`dpnp.equal` but not :obj:`dpnp.array_equal`.
+
     Examples
     --------
     >>> import dpnp as np
@@ -538,6 +546,8 @@ def array_equiv(a1, a2):
 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).
 out : {None, dpnp.ndarray, usm_ndarray}, optional
     Output array to populate.
     Array have the correct shape and the expected data type.
@@ -609,6 +619,8 @@ def array_equiv(a1, a2):
 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).
 out : {None, dpnp.ndarray, usm_ndarray}, optional
     Output array to populate.
     Array must have the correct shape and the expected data type.
@@ -675,6 +687,8 @@ def array_equiv(a1, a2):
 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).
 out : {None, dpnp.ndarray, usm_ndarray}, optional
     Output array to populate.
     Array must have the correct shape and the expected data type.
@@ -753,9 +767,11 @@ def isclose(a, b, rtol=1e-05, atol=1e-08, equal_nan=False):
         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. Default: ``1e-05``.
+        The relative tolerance parameter.
+        Default: ``1e-05``.
     atol : {dpnp.ndarray, usm_ndarray, scalar}, optional
-        The absolute tolerance parameter. Default: ``1e-08``.
+        The absolute tolerance parameter.
+        Default: ``1e-08``.
     equal_nan : bool
         Whether to compare ``NaNs`` as equal. If ``True``, ``NaNs`` in `a` will
         be considered equal to ``NaNs`` in `b` in the output array.
@@ -1446,6 +1462,8 @@ def isscalar(element):
 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).
 out : {None, dpnp.ndarray, usm_ndarray}, optional
     Output array to populate.
     Array must have the correct shape and the expected data type.
@@ -1512,6 +1530,8 @@ def isscalar(element):
 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).
 out : {None, dpnp.ndarray, usm_ndarray}, optional
     Output array to populate.
     Array must have the correct shape and the expected data type.
@@ -1578,6 +1598,8 @@ def isscalar(element):
 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).
 out : {None, dpnp.ndarray, usm_ndarray}, optional
     Output array to populate.
     Array must have the correct shape and the expected data type.
@@ -1590,6 +1612,7 @@ def isscalar(element):
 -------
 out : dpnp.ndarray
     An array containing the element-wise logical AND results.
+    The shape is determined by broadcasting.
 
 Limitations
 -----------
@@ -1699,6 +1722,8 @@ def isscalar(element):
 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).
 out : {None, dpnp.ndarray, usm_ndarray}, optional
     Output array to populate.
     Array must have the correct shape and the expected data type.
@@ -1711,6 +1736,7 @@ def isscalar(element):
 -------
 out : dpnp.ndarray
     An array containing the element-wise logical OR results.
+    The shape is determined by broadcasting.
 
 Limitations
 -----------
@@ -1767,6 +1793,8 @@ def isscalar(element):
 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).
 out : {None, dpnp.ndarray, usm_ndarray}, optional
     Output array to populate.
     Array must have the correct shape and the expected data type.
@@ -1779,6 +1807,7 @@ def isscalar(element):
 -------
 out : dpnp.ndarray
     An array containing the element-wise logical XOR results.
+    The shape is determined by broadcasting.
 
 Limitations
 -----------
@@ -1833,6 +1862,8 @@ def isscalar(element):
 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).
 out : {None, dpnp.ndarray, usm_ndarray}, optional
     Output array to populate.
     Array must have the correct shape and the expected data type.

dpnp/dpnp_iface_mathematical.py

@@ -428,6 +428,8 @@ def _process_ediff1d_args(arg, arg_name, ary_dtype, ary_sycl_queue, usm_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).
 out : {None, dpnp.ndarray, usm_ndarray}, optional
     Output array to populate.
     Array must have the correct shape and the expected data type.
@@ -791,7 +793,7 @@ def convolve(a, v, mode="full"):
     return call_origin(numpy.convolve, a=a, v=v, mode=mode)
 
 
-_COPYSING_DOCSTRING = """
+_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`.
 
@@ -806,6 +808,8 @@ def convolve(a, v, mode="full"):
     Second input array, also expected to have a real 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.
@@ -852,7 +856,7 @@ def convolve(a, v, mode="full"):
     "copysign",
     ti._copysign_result_type,
     ti._copysign,
-    _COPYSING_DOCSTRING,
+    _COPYSIGN_DOCSTRING,
 )
 
 
@@ -1462,6 +1466,8 @@ def diff(a, n=1, axis=-1, prepend=None, append=None):
 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).
 out : {None, dpnp.ndarray, usm_ndarray}, optional
     Output array to populate.
     Array must have the correct shape and the expected data type.
@@ -1759,6 +1765,8 @@ def ediff1d(ary, to_end=None, to_begin=None):
 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).
 out : {None, dpnp.ndarray, usm_ndarray}, optional
     Output array to populate. Array must have the correct shape and
     the expected data type.
@@ -1910,6 +1918,8 @@ def ediff1d(ary, to_end=None, to_begin=None):
 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).
 out : {None, dpnp.ndarray, usm_ndarray}, optional
     Output array to populate.
     Array must have the correct shape and the expected data type.
@@ -1984,6 +1994,8 @@ def ediff1d(ary, to_end=None, to_begin=None):
 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).
 out : {None, dpnp.ndarray, usm_ndarray}, optional
     Output array to populate.
     Array must have the correct shape and the expected data type.
@@ -2069,6 +2081,8 @@ def ediff1d(ary, to_end=None, to_begin=None):
 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).
 out : {None, dpnp.ndarray, usm_ndarray}, optional
     Output array to populate.
     Array must have the correct shape and the expected data type.
@@ -2151,6 +2165,8 @@ def ediff1d(ary, to_end=None, to_begin=None):
 x2 : {dpnp.ndarray, usm_ndarray, scalar}
     Second input array, also expected to have a real-valued 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.
@@ -2220,8 +2236,8 @@ def ediff1d(ary, to_end=None, to_begin=None):
 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.
-x : {dpnp.ndarray, usm_ndarray}
-    An array of floats to be rounded.
+    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.
@@ -2484,6 +2500,8 @@ def gradient(f, *varargs, axis=None, edge_order=1):
 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).
 out : {None, dpnp.ndarray, usm_ndarray}, optional
     Output array to populate.
     Array must have the correct shape and the expected data type.
@@ -2636,6 +2654,8 @@ def gradient(f, *varargs, axis=None, edge_order=1):
 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.
@@ -2693,6 +2713,8 @@ def gradient(f, *varargs, axis=None, edge_order=1):
 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.
@@ -2758,6 +2780,8 @@ def gradient(f, *varargs, axis=None, edge_order=1):
 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).
 out : {None, dpnp.ndarray, usm_ndarray}, optional
     Output array to populate.
     Array must have the correct shape and the expected data type.
@@ -2838,6 +2862,8 @@ def gradient(f, *varargs, axis=None, edge_order=1):
 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
 out : {None, dpnp.ndarray, usm_ndarray}, optional
     Output array to populate.
     Array must have the correct shape and the expected data type.
@@ -2943,6 +2969,8 @@ def modf(x1, **kwargs):
 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).
 out : {None, dpnp.ndarray, usm_ndarray}, optional
     Output array to populate.
     Array must have the correct shape and the expected data type.
@@ -3205,6 +3233,8 @@ def nan_to_num(x, copy=True, nan=0.0, posinf=None, neginf=None):
 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).
 out : {None, dpnp.ndarray, usm_ndarray}, optional
     Output array to populate. Array must have the correct shape and
     the expected data type.
@@ -3326,6 +3356,8 @@ def nan_to_num(x, copy=True, nan=0.0, posinf=None, neginf=None):
 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).
 out : {None, dpnp.ndarray, usm_ndarray}, optional
     Output array to populate. Array must have the correct shape and
     the expected data type.
@@ -3688,6 +3720,8 @@ def real_if_close(a, tol=100):
 x2 : {dpnp.ndarray, usm_ndarray, scalar}
     Second input array, also expected to have a real-valued 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.
@@ -4114,6 +4148,8 @@ def real_if_close(a, tol=100):
 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).
 out : {None, dpnp.ndarray, usm_ndarray}, optional
     Output array to populate.
     Array must have the correct shape and the expected data type.