Update logic func docs adding broadcast info

Author: vlad-perevezentsev

dpnp/dpnp_iface_logic.py

@@ -192,16 +192,15 @@ 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.
-        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.
+    a, b : {dpnp.ndarray, usm_ndarray, scalar}
+        Input arrays, 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 +212,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
@@ -348,11 +353,8 @@ def array_equal(a1, a2, equal_nan=False):
 
     Parameters
     ----------
-    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.
+    a1, a2 : {dpnp.ndarray, usm_ndarray, scalar}
+        Input arrays.
         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
@@ -473,11 +475,8 @@ def array_equiv(a1, a2):
 
     Parameters
     ----------
-    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.
+    a1, a2 : {dpnp.ndarray, usm_ndarray, scalar}
+        Input arrays.
         Both inputs `x1` and `x2` can not be scalars at the same time.
 
     Returns
@@ -532,15 +531,16 @@ def array_equiv(a1, a2):
 
 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.
-x2 : {dpnp.ndarray, usm_ndarray, scalar}
-    Second input array, also expected to have numeric data type.
+x1, x2 : {dpnp.ndarray, usm_ndarray, scalar}
+    Input arrays, 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.
+    Array must have a shape that the inputs broadcast to and
+    the expected data type.
+    Default: ``None``.
 order : {"C", "F", "A", "K"}, optional
     Memory layout of the newly output array, if parameter `out` is ``None``.
     Default: ``"K"``.
@@ -603,15 +603,15 @@ def array_equiv(a1, a2):
 
 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.
-x2 : {dpnp.ndarray, usm_ndarray, scalar}
-    Second input array, also expected to have numeric data type.
+x1, x2 : {dpnp.ndarray, usm_ndarray, scalar}
+    Input arrays, 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.
+    Array must have a shape that the inputs broadcast to and
+    the expected data type.
     Default: ``None``.
 order : {"C", "F", "A", "K"}, optional
     Memory layout of the newly output array, if parameter `out` is ``None``.
@@ -669,15 +669,15 @@ def array_equiv(a1, a2):
 
 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.
-x2 : {dpnp.ndarray, usm_ndarray, scalar}
-    Second input array, also expected to have numeric data type.
+x1, x2 : {dpnp.ndarray, usm_ndarray, scalar}
+    Input arrays, 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.
+    Array must have a shape that the inputs broadcast to and
+    the expected data type.
     Default: ``None``.
 order : {"C", "F", "A", "K"}, optional
     Memory layout of the newly output array, if parameter `out` is ``None``.
@@ -746,16 +746,15 @@ 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.
-        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.
+    a, b : {dpnp.ndarray, usm_ndarray, scalar}
+        Input arrays to compare, 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.
@@ -943,7 +942,8 @@ def iscomplexobj(x):
     Input array, expected to have 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.
+    Array must have a shape that the input broadcast to and
+    the expected data type.
     Default: ``None``.
 order : {"C", "F", "A", "K"}, optional
     Memory layout of the newly output array, if parameter `out` is ``None``.
@@ -1073,7 +1073,8 @@ def isfortran(a):
     Input array, expected to have 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.
+    Array must have a shape that the input broadcast to and
+    the expected data type.
     Default: ``None``.
 order : {"C", "F", "A", "K"}, optional
     Memory layout of the newly output array, if parameter `out` is ``None``.
@@ -1127,7 +1128,8 @@ def isfortran(a):
     Input array, expected to have 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.
+    Array must have a shape that the input broadcast to and
+    the expected data type.
     Default: ``None``.
 order : {"C", "F", "A", "K"}, optional
     Memory layout of the newly output array, if parameter `out` is ``None``.
@@ -1440,15 +1442,15 @@ def isscalar(element):
 
 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.
-x2 : {dpnp.ndarray, usm_ndarray, scalar}
-    Second input array, also expected to have numeric data type.
+x1, x2 : {dpnp.ndarray, usm_ndarray, scalar}
+    Input arrays, 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.
+    Array must have a shape that the inputs broadcast to and
+    the expected data type.
     Default: ``None``.
 order : {"C", "F", "A", "K"}, optional
     Memory layout of the newly output array, if parameter `out` is ``None``.
@@ -1506,15 +1508,15 @@ def isscalar(element):
 
 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.
-x2 : {dpnp.ndarray, usm_ndarray, scalar}
-    Second input array, also expected to have numeric data type.
+x1, x2 : {dpnp.ndarray, usm_ndarray, scalar}
+    Input arrays, 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.
+    Array must have a shape that the inputs broadcast to and
+    the expected data type.
     Default: ``None``.
 order : {"C", "F", "A", "K"}, optional
     Memory layout of the newly output array, if parameter `out` is ``None``.
@@ -1572,15 +1574,15 @@ def isscalar(element):
 
 Parameters
 ----------
-x1 : {dpnp.ndarray, usm_ndarray, scalar}
-    First input array.
-    Both inputs `x1` and `x2` can not be scalars at the same time.
-x2 : {dpnp.ndarray, usm_ndarray, scalar}
-    Second input array.
+x1, x2 : {dpnp.ndarray, usm_ndarray, scalar}
+    Input arrays, 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.
+    Array must have a shape that the inputs broadcast to and
+    the expected data type.
     Default: ``None``.
 order : {"C", "F", "A", "K"}, optional
     Memory layout of the newly output array, if parameter `out` is ``None``.
@@ -1590,6 +1592,7 @@ def isscalar(element):
 -------
 out : dpnp.ndarray
     An array containing the element-wise logical AND results.
+    The shape is determined by broadcasting.
 
 Limitations
 -----------
@@ -1643,7 +1646,8 @@ def isscalar(element):
     Input array.
 out : {None, dpnp.ndarray, usm_ndarray}, optional
     Output array to populate.
-    Array must have the correct shape and the expected data type.
+    Array must have a shape that the input broadcast to and
+    the expected data type.
     Default: ``None``.
 order : {"C", "F", "A", "K"}, optional
     Memory layout of the newly output array, if parameter `out` is ``None``.
@@ -1693,15 +1697,15 @@ def isscalar(element):
 
 Parameters
 ----------
-x1 : {dpnp.ndarray, usm_ndarray, scalar}
-    First input array.
-    Both inputs `x1` and `x2` can not be scalars at the same time.
-x2 : {dpnp.ndarray, usm_ndarray, scalar}
-    Second input array.
+x1, x2 : {dpnp.ndarray, usm_ndarray, scalar}
+    Input arrays, 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.
+    Array must have a shape that the inputs broadcast to and
+    the expected data type.
     Default: ``None``.
 order : {"C", "F", "A", "K"}, optional
     Memory layout of the newly output array, if parameter `out` is ``None``.
@@ -1711,6 +1715,7 @@ def isscalar(element):
 -------
 out : dpnp.ndarray
     An array containing the element-wise logical OR results.
+    The shape is determined by broadcasting.
 
 Limitations
 -----------
@@ -1761,15 +1766,15 @@ def isscalar(element):
 
 Parameters
 ----------
-x1 : {dpnp.ndarray, usm_ndarray, scalar}
-    First input array.
-    Both inputs `x1` and `x2` can not be scalars at the same time.
-x2 : {dpnp.ndarray, usm_ndarray, scalar}
-    Second input array.
+x1, x2 : {dpnp.ndarray, usm_ndarray, scalar}
+    Input arrays, 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.
+    Array must have a shape that the inputs broadcast to and
+    the expected data type.
     Default: ``None``.
 order : {"C", "F", "A", "K"}, optional
     Memory layout of the newly output array, if parameter `out` is ``None``.
@@ -1779,6 +1784,7 @@ def isscalar(element):
 -------
 out : dpnp.ndarray
     An array containing the element-wise logical XOR results.
+    The shape is determined by broadcasting.
 
 Limitations
 -----------
@@ -1827,15 +1833,15 @@ def isscalar(element):
 
 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.
-x2 : {dpnp.ndarray, usm_ndarray, scalar}
-    Second input array, also expected to have numeric data type.
+x1, x2 : {dpnp.ndarray, usm_ndarray, scalar}
+    Input arrays, 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.
+    Array must have a shape that the inputs broadcast to and
+    the expected data type.
     Default: ``None``.
 order : {"C", "F", "A", "K"}, optional
     Memory layout of the newly output array, if parameter `out` is ``None``.