Add python implementation of divmod

Author: antonwolfy

dpnp/dpnp_iface_mathematical.py

@@ -66,6 +66,7 @@
     DPNPAngle,
     DPNPBinaryFunc,
     DPNPBinaryFuncOutKw,
+    DPNPBinaryTwoOutputsFunc,
     DPNPFix,
     DPNPImag,
     DPNPReal,
@@ -102,6 +103,7 @@
     "cumulative_prod",
     "cumulative_sum",
     "diff",
+    "divmod",
     "divide",
     "ediff1d",
     "fabs",
@@ -1630,6 +1632,100 @@ def diff(a, n=1, axis=-1, prepend=None, append=None):
 )
 
 
+_DIVMOD_DOCSTRING = r"""
+Calculates the quotient and the remainder 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.divmod`.
+
+Parameters
+----------
+x1 : {dpnp.ndarray, usm_ndarray}
+    Dividend input array, expected to have a real-valued floating-point data
+    type.
+x2 : {dpnp.ndarray, usm_ndarray}
+    Divisor input array, expected to have a real-valued floating-point data
+    type.
+out1 : {None, dpnp.ndarray, usm_ndarray}, optional
+    Output array for the quotient to populate. Array must have the same shape
+    as `x` and the expected data type.
+
+    Default: ``None``.
+out2 : {None, dpnp.ndarray, usm_ndarray}, optional
+    Output array for the remainder to populate. Array must have the same shape
+    as `x` and the expected data type.
+
+    Default: ``None``.
+out : tuple of None, dpnp.ndarray, or usm_ndarray, optional
+    A location into which the result is stored. If provided, it must be a tuple
+    and have length equal to the number of outputs. Each provided array must
+    have the same shape as `x` and the expected data type.
+    It is prohibited to pass output arrays through `out` keyword when either
+    `out1` or `out2` is passed.
+
+    Default: ``(None, None)``.
+order : {None, "C", "F", "A", "K"}, optional
+    Memory layout of the newly output array, if parameter `out` is ``None``.
+
+    Default: ``"K"``.
+
+Returns
+-------
+quotient : dpnp.ndarray
+    Element-wise quotient resulting from floor division.
+remainder : dpnp.ndarray
+    Element-wise remainder from floor division.
+
+Limitations
+-----------
+Parameters `where`, `dtype` and `subok` are supported with their default values.
+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).
+
+Equivalent to :math:`(x1 // x2, x1 \% x2)`, but faster because it avoids
+redundant work. It is used to implement the Python built-in function ``divmod``
+on :class:`dpnp.ndarray`.
+
+Complex dtypes are not supported, they will raise a ``TypeError``.
+
+See Also
+--------
+:obj:`dpnp.floor_divide` : Equivalent to Python's :math:`//` operator.
+:obj:`dpnp.remainder` : Equivalent to Python's :math:`\%` operator.
+:obj:`dpnp.modf` : Equivalent to ``divmod(x, 1)`` for positive `x` with the
+    return values switched.
+
+Examples
+--------
+>>> import dpnp as np
+>>> np.divmod(np.arange(5), 3)
+(array([0, 0, 0, 1, 1]), array([0, 1, 2, 0, 1]))
+
+The Python built-in function ``divmod`` function can be used as a shorthand for
+``np.divmod`` on :class:`dpnp.ndarray`.
+
+>>> x = np.arange(5)
+>>> divmod(x, 3)
+(array([0, 0, 0, 1, 1]), array([0, 1, 2, 0, 1]))
+
+"""
+
+divmod = DPNPBinaryTwoOutputsFunc(
+    "divmod",
+    ufi._divmod_result_type,
+    ufi._divmod,
+    _DIVMOD_DOCSTRING,
+)
+
+
 def ediff1d(ary, to_end=None, to_begin=None):
     """
     The differences between consecutive elements of an array.
@@ -2065,6 +2161,7 @@ def ediff1d(ary, to_end=None, to_begin=None):
 See Also
 --------
 :obj:`dpnp.remainder` : Remainder complementary to floor_divide.
+:obj:`dpnp.divmod` : Simultaneous floor division and remainder.
 :obj:`dpnp.divide` : Standard division.
 :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.
@@ -2445,7 +2542,7 @@ def ediff1d(ary, to_end=None, to_begin=None):
 """
 
 frexp = DPNPUnaryTwoOutputsFunc(
-    "_frexp",
+    "frexp",
     ufi._frexp_result_type,
     ufi._frexp,
     _FREXP_DOCSTRING,
@@ -3207,7 +3304,7 @@ def interp(x, xp, fp, left=None, right=None, period=None):
 """
 
 ldexp = DPNPBinaryFunc(
-    "_ldexp",
+    "ldexp",
     ufi._ldexp_result_type,
     ufi._ldexp,
     _LDEXP_DOCSTRING,
@@ -3487,7 +3584,7 @@ def interp(x, xp, fp, left=None, right=None, period=None):
 """
 
 modf = DPNPUnaryTwoOutputsFunc(
-    "_modf",
+    "modf",
     ufi._modf_result_type,
     ufi._modf,
     _MODF_DOCSTRING,
@@ -4344,6 +4441,7 @@ def real_if_close(a, tol=100):
 See Also
 --------
 :obj:`dpnp.fmod` : Calculate the element-wise remainder of division.
+:obj:`dpnp.divmod` : Simultaneous floor division and remainder.
 :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