diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 324309b3811e..1b5bd46e5e56 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -94,4 +94,4 @@ repos: "--disable=redefined-builtin", "--disable=unused-wildcard-import" ] - files: '^dpnp/dpnp_iface(|_arraycreation|_counting|_indexing|_libmath|_linearalgebra|_manipulation|_nanfunctions|_searching|_sorting|_statistics|_types).py$' + files: '^dpnp/dpnp_iface.*' diff --git a/doc/conf.py b/doc/conf.py index 037adf6c4198..9fe964e8cc3b 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -6,6 +6,10 @@ # full list see the documentation: # http://www.sphinx-doc.org/en/master/config +from sphinx.ext.autodoc import FunctionDocumenter + +from dpnp.dpnp_algo.dpnp_elementwise_common import DPNPBinaryFunc, DPNPUnaryFunc + try: import comparison_generator except ImportError: @@ -188,7 +192,17 @@ # -- Extension configuration ------------------------------------------------- + # -- Options for todo extension ---------------------------------------------- +def _can_document_member(member, *args, **kwargs): + if isinstance(member, (DPNPBinaryFunc, DPNPUnaryFunc)): + return True + return orig(member, *args, **kwargs) + + +documenter = FunctionDocumenter +orig = documenter.can_document_member +documenter.can_document_member = _can_document_member autosummary_generate = True diff --git a/dpnp/dpnp_algo/dpnp_elementwise_common.py b/dpnp/dpnp_algo/dpnp_elementwise_common.py index f88b226ba65a..833138ba13be 100644 --- a/dpnp/dpnp_algo/dpnp_elementwise_common.py +++ b/dpnp/dpnp_algo/dpnp_elementwise_common.py @@ -24,3096 +24,448 @@ # THE POSSIBILITY OF SUCH DAMAGE. # ***************************************************************************** - -import dpctl.tensor as dpt +import numpy +from dpctl.tensor._elementwise_common import ( + BinaryElementwiseFunc, + UnaryElementwiseFunc, +) import dpnp -import dpnp.backend.extensions.vm._vm_impl as vmi from dpnp.dpnp_array import dpnp_array -from dpnp.dpnp_utils import call_origin __all__ = [ - "check_nd_call_func", - "dpnp_abs", - "dpnp_acos", - "dpnp_acosh", - "dpnp_add", - "dpnp_angle", - "dpnp_asin", - "dpnp_asinh", - "dpnp_atan", - "dpnp_atan2", - "dpnp_atanh", - "dpnp_bitwise_and", - "dpnp_bitwise_or", - "dpnp_bitwise_xor", - "dpnp_cbrt", - "dpnp_ceil", - "dpnp_conj", - "dpnp_copysign", - "dpnp_cos", - "dpnp_cosh", - "dpnp_divide", - "dpnp_equal", - "dpnp_exp", - "dpnp_exp2", - "dpnp_expm1", - "dpnp_floor", - "dpnp_floor_divide", - "dpnp_greater", - "dpnp_greater_equal", - "dpnp_hypot", - "dpnp_imag", - "dpnp_invert", - "dpnp_isfinite", - "dpnp_isinf", - "dpnp_isnan", - "dpnp_left_shift", - "dpnp_less", - "dpnp_less_equal", - "dpnp_log", - "dpnp_log10", - "dpnp_log1p", - "dpnp_log2", - "dpnp_logaddexp", - "dpnp_logical_and", - "dpnp_logical_not", - "dpnp_logical_or", - "dpnp_logical_xor", - "dpnp_maximum", - "dpnp_minimum", - "dpnp_multiply", - "dpnp_negative", - "dpnp_positive", - "dpnp_not_equal", - "dpnp_power", - "dpnp_proj", - "dpnp_real", - "dpnp_reciprocal", - "dpnp_remainder", - "dpnp_right_shift", - "dpnp_round", - "dpnp_rsqrt", - "dpnp_sign", - "dpnp_signbit", - "dpnp_sin", - "dpnp_sinh", - "dpnp_sqrt", - "dpnp_square", - "dpnp_subtract", - "dpnp_tan", - "dpnp_tanh", - "dpnp_trunc", + "acceptance_fn_negative", + "acceptance_fn_positive", + "acceptance_fn_sign", + "acceptance_fn_subtract", + "DPNPAngle", + "DPNPBinaryFunc", + "DPNPReal", + "DPNPRound", + "DPNPUnaryFunc", ] -def check_nd_call_func( - origin_func, - dpnp_func, - *x_args, - out=None, - where=True, - order="K", - dtype=None, - subok=True, - **kwargs, -): - """ - Checks arguments and calls a function. - - Chooses a common internal elementwise function to call in DPNP based on input arguments - or to fallback on NumPy call if any passed argument is not currently supported. - - """ - - args_len = len(x_args) - if kwargs: - pass - elif where is not True: - pass - elif dtype is not None: - pass - elif subok is not True: - pass - elif args_len < 1 or args_len > 2: - raise ValueError( - "Unsupported number of input arrays to pass in elementwise function {}".format( - dpnp_func.__name__ - ) +class DPNPUnaryFunc(UnaryElementwiseFunc): + """ + Class that implements unary element-wise functions. + + Parameters + ---------- + name : {str} + Name of the unary function + result_type_resovler_fn : {callable} + Function that takes dtype of the input and returns the dtype of + the result if the implementation functions supports it, or + returns `None` otherwise. + unary_dp_impl_fn : {callable} + Data-parallel implementation function with signature + `impl_fn(src: usm_ndarray, dst: usm_ndarray, + sycl_queue: SyclQueue, depends: Optional[List[SyclEvent]])` + where the `src` is the argument array, `dst` is the + array to be populated with function values, effectively + evaluating `dst = func(src)`. + The `impl_fn` is expected to return a 2-tuple of `SyclEvent`s. + The first event corresponds to data-management host tasks, + including lifetime management of argument Python objects to ensure + that their associated USM allocation is not freed before offloaded + computational tasks complete execution, while the second event + corresponds to computational tasks associated with function evaluation. + docs : {str} + Documentation string for the unary function. + mkl_fn_to_call : {callable} + Check input arguments to answer if function from OneMKL VM library + can be used. + mkl_impl_fn : {callable} + Function from OneMKL VM library to call. + acceptance_fn : {callable}, optional + Function to influence type promotion behavior of this unary + function. The function takes 4 arguments: + arg_dtype - Data type of the first argument + buf_dtype - Data type the argument would be cast to + res_dtype - Data type of the output array with function values + sycl_dev - The :class:`dpctl.SyclDevice` where the function + evaluation is carried out. + The function is invoked when the argument of the unary function + requires casting, e.g. the argument of `dpctl.tensor.log` is an + array with integral data type. + """ + + def __init__( + self, + name, + result_type_resolver_fn, + unary_dp_impl_fn, + docs, + mkl_fn_to_call=None, + mkl_impl_fn=None, + acceptance_fn=None, + ): + def _call_func(src, dst, sycl_queue, depends=None): + """ + A callback to register in UnaryElementwiseFunc class of + dpctl.tensor + """ + + if depends is None: + depends = [] + + if mkl_fn_to_call is not None and mkl_fn_to_call( + sycl_queue, src, dst + ): + # call pybind11 extension for unary function from OneMKL VM + return mkl_impl_fn(sycl_queue, src, dst, depends) + return unary_dp_impl_fn(src, dst, sycl_queue, depends) + + super().__init__( + name, + result_type_resolver_fn, + _call_func, + docs, + acceptance_fn=acceptance_fn, ) - elif args_len == 1 and dpnp.isscalar(x_args[0]): - # input has to be an array - pass - elif ( - args_len == 2 and dpnp.isscalar(x_args[0]) and dpnp.isscalar(x_args[1]) + self.__name__ = "DPNPUnaryFunc" + + def __call__( + self, + x, + out=None, + where=True, + order="K", + dtype=None, + subok=True, + **kwargs, ): - # at least one of input has to be an array - pass - else: - if order in "afkcAFKC": - order = order.upper() - elif order is None: - order = "K" + if kwargs: + raise NotImplementedError( + f"Requested function={self.name_} with kwargs={kwargs} " + "isn't currently supported." + ) + elif where is not True: + raise NotImplementedError( + f"Requested function={self.name_} with where={where} " + "isn't currently supported." + ) + elif subok is not True: + raise NotImplementedError( + f"Requested function={self.name_} with subok={subok} " + "isn't currently supported." + ) + elif not dpnp.is_supported_array_type(x): + raise TypeError( + "Input array must be any of supported type, " + f"but got {type(x)}" + ) + elif dtype is not None and out is not None: + raise TypeError( + f"Requested function={self.name_} only takes `out` or `dtype`" + "as an argument, but both were provided." + ) else: - raise ValueError( - "order must be one of 'C', 'F', 'A', or 'K' (got '{}')".format( - order + if order is None: + order = "K" + elif order in "afkcAFKC": + order = order.upper() + else: + raise ValueError( + "order must be one of 'C', 'F', 'A', or 'K' " + f"(got '{order}')" ) - ) - return dpnp_func(*x_args, out=out, order=order) - if origin_func is not None: - return call_origin( - origin_func, - *x_args, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, + if dtype is not None: + x = dpnp.astype(x, dtype=dtype, copy=False) + x_usm = dpnp.get_usm_ndarray(x) + out_usm = None if out is None else dpnp.get_usm_ndarray(out) + res_usm = super().__call__(x_usm, out=out_usm, order=order) + if out is not None and isinstance(out, dpnp_array): + return out + return dpnp_array._create_from_usm_ndarray(res_usm) + + +class DPNPBinaryFunc(BinaryElementwiseFunc): + """ + Class that implements binary element-wise functions. + + Args: + name : {str} + Name of the unary function + result_type_resovle_fn : {callable} + Function that takes dtype of the input and returns the dtype of + the result if the implementation functions supports it, or + returns `None` otherwise.. + binary_dp_impl_fn : {callable} + Data-parallel implementation function with signature + `impl_fn(src1: usm_ndarray, src2: usm_ndarray, dst: usm_ndarray, + sycl_queue: SyclQueue, depends: Optional[List[SyclEvent]])` + where the `src1` and `src2` are the argument arrays, `dst` is the + array to be populated with function values, + i.e. `dst=func(src1, src2)`. + The `impl_fn` is expected to return a 2-tuple of `SyclEvent`s. + The first event corresponds to data-management host tasks, + including lifetime management of argument Python objects to ensure + that their associated USM allocation is not freed before offloaded + computational tasks complete execution, while the second event + corresponds to computational tasks associated with function + evaluation. + docs : {str} + Documentation string for the unary function. + mkl_fn_to_call : {callable} + Check input arguments to answer if function from OneMKL VM library + can be used. + mkl_impl_fn : {callable} + Function from OneMKL VM library to call. + binary_inplace_fn : {callable}, optional + Data-parallel implementation function with signature + `impl_fn(src: usm_ndarray, dst: usm_ndarray, + sycl_queue: SyclQueue, depends: Optional[List[SyclEvent]])` + where the `src` is the argument array, `dst` is the + array to be populated with function values, + i.e. `dst=func(dst, src)`. + The `impl_fn` is expected to return a 2-tuple of `SyclEvent`s. + The first event corresponds to data-management host tasks, + including async lifetime management of Python arguments, + while the second event corresponds to computational tasks + associated with function evaluation. + acceptance_fn : {callable}, optional + Function to influence type promotion behavior of this binary + function. The function takes 6 arguments: + arg1_dtype - Data type of the first argument + arg2_dtype - Data type of the second argument + ret_buf1_dtype - Data type the first argument would be cast to + ret_buf2_dtype - Data type the second argument would be cast to + res_dtype - Data type of the output array with function values + sycl_dev - The :class:`dpctl.SyclDevice` where the function + evaluation is carried out. + The function is only called when both arguments of the binary + function require casting, e.g. both arguments of + `dpctl.tensor.logaddexp` are arrays with integral data type. + """ + + def __init__( + self, + name, + result_type_resolver_fn, + binary_dp_impl_fn, + docs, + mkl_fn_to_call=None, + mkl_impl_fn=None, + binary_inplace_fn=None, + acceptance_fn=None, + ): + def _call_func(src1, src2, dst, sycl_queue, depends=None): + """ + A callback to register in UnaryElementwiseFunc class of + dpctl.tensor + """ + + if depends is None: + depends = [] + + if mkl_fn_to_call is not None and mkl_fn_to_call( + sycl_queue, src1, src2, dst + ): + # call pybind11 extension for binary function from OneMKL VM + return mkl_impl_fn(sycl_queue, src1, src2, dst, depends) + return binary_dp_impl_fn(src1, src2, dst, sycl_queue, depends) + + super().__init__( + name, + result_type_resolver_fn, + _call_func, + docs, + binary_inplace_fn, + acceptance_fn=acceptance_fn, ) - else: - raise NotImplementedError( - f"Requested function={dpnp_func.__name__} with args={x_args} and kwargs={kwargs} " - "isn't currently supported." + self.__name__ = "DPNPBinaryFunc" + + def __call__( + self, + x1, + x2, + out=None, + where=True, + order="K", + dtype=None, + subok=True, + **kwargs, + ): + dpnp.check_supported_arrays_type( + x1, x2, scalar_type=True, all_scalars=False ) - - -def _get_result(res_usm, out=None): - if out is None: - return dpnp_array._create_from_usm_ndarray(res_usm) - else: - return out - - -def _make_unary_func( - name, dpt_unary_fn, fn_docstring, mkl_fn_to_call=None, mkl_impl_fn=None -): - impl_fn = dpt_unary_fn.get_implementation_function() - type_resolver_fn = dpt_unary_fn.get_type_result_resolver_function() - acceptance_fn = dpt_unary_fn.get_type_promotion_path_acceptance_function() - - def _call_func(src, dst, sycl_queue, depends=None): - """A callback to register in UnaryElementwiseFunc class of dpctl.tensor""" - - if depends is None: - depends = [] - - if mkl_fn_to_call is not None and mkl_fn_to_call(sycl_queue, src, dst): - # call pybind11 extension for unary function from OneMKL VM - return mkl_impl_fn(sycl_queue, src, dst, depends) - return impl_fn(src, dst, sycl_queue, depends) - - func = dpt_unary_fn.__class__( - name, type_resolver_fn, _call_func, fn_docstring, acceptance_fn - ) - return func - - -def _make_binary_func( - name, dpt_binary_fn, fn_docstring, mkl_fn_to_call=None, mkl_impl_fn=None -): - impl_fn = dpt_binary_fn.get_implementation_function() - type_resolver_fn = dpt_binary_fn.get_type_result_resolver_function() - inplce_fn = dpt_binary_fn.get_implementation_inplace_function() - acceptance_fn = dpt_binary_fn.get_type_promotion_path_acceptance_function() - - def _call_func(src1, src2, dst, sycl_queue, depends=None): - """A callback to register in UnaryElementwiseFunc class of dpctl.tensor""" - - if depends is None: - depends = [] - - if mkl_fn_to_call is not None and mkl_fn_to_call( - sycl_queue, src1, src2, dst - ): - # call pybind11 extension for binary function from OneMKL VM - return mkl_impl_fn(sycl_queue, src1, src2, dst, depends) - return impl_fn(src1, src2, dst, sycl_queue, depends) - - func = dpt_binary_fn.__class__( + if kwargs: + raise NotImplementedError( + f"Requested function={self.name_} with kwargs={kwargs} " + "isn't currently supported." + ) + elif where is not True: + raise NotImplementedError( + f"Requested function={self.name_} with where={where} " + "isn't currently supported." + ) + elif subok is not True: + raise NotImplementedError( + f"Requested function={self.name_} with subok={subok} " + "isn't currently supported." + ) + elif dtype is not None and out is not None: + raise TypeError( + f"Requested function={self.name_} only takes `out` or `dtype`" + "as an argument, but both were provided." + ) + else: + if order is None: + order = "K" + elif order in "afkcAFKC": + order = order.upper() + else: + raise ValueError( + "order must be one of 'C', 'F', 'A', or 'K' " + f"(got '{order}')" + ) + if dtype is not None: + if dpnp.isscalar(x1): + x1 = dpnp.asarray(x1, dtype=dtype) + x2 = dpnp.astype(x2, dtype=dtype, copy=False) + elif dpnp.isscalar(x2): + x1 = dpnp.astype(x1, dtype=dtype, copy=False) + x2 = dpnp.asarray(x2, dtype=dtype) + else: + x1 = dpnp.astype(x1, dtype=dtype, copy=False) + x2 = dpnp.astype(x2, dtype=dtype, copy=False) + + x1_usm = dpnp.get_usm_ndarray_or_scalar(x1) + x2_usm = dpnp.get_usm_ndarray_or_scalar(x2) + + out_usm = None if out is None else dpnp.get_usm_ndarray(out) + res_usm = super().__call__(x1_usm, x2_usm, out=out_usm, order=order) + if out is not None and isinstance(out, dpnp_array): + return out + return dpnp_array._create_from_usm_ndarray(res_usm) + + +class DPNPAngle(DPNPUnaryFunc): + """Class that implements dpnp.angle unary element-wise functions.""" + + def __init__( + self, name, - type_resolver_fn, - _call_func, - fn_docstring, - inplce_fn, - acceptance_fn, - ) - return func - - -_abs_docstring = """ -abs(x, out=None, order='K') - -Calculates the absolute value for each element `x_i` of input array `x`. - -Args: - x (dpnp.ndarray): - Input array, expected to have numeric data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Return: - 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 - 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`. -""" - -abs_func = _make_unary_func( - "abs", dpt.abs, _abs_docstring, vmi._mkl_abs_to_call, vmi._abs -) - - -def dpnp_abs(x, out=None, order="K"): - """ - Invokes abs() function from pybind11 extension of OneMKL VM if possible. - - Otherwise fully relies on dpctl.tensor implementation for abs() function. - - """ - # dpctl.tensor only works with usm_ndarray - x1_usm = dpnp.get_usm_ndarray(x) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = abs_func(x1_usm, out=out_usm, order=order) - return _get_result(res_usm, out=out) - - -_acos_docstring = """ -acos(x, out=None, order='K') - -Computes inverse cosine for each element `x_i` for input array `x`. - -Args: - x (dpnp.ndarray): - Input array, expected to have numeric data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Return: - 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. -""" - -acos_func = _make_unary_func( - "arccos", dpt.acos, _acos_docstring, vmi._mkl_acos_to_call, vmi._acos -) - - -def dpnp_acos(x, out=None, order="K"): - """ - Invokes acos() function from pybind11 extension of OneMKL VM if possible. - - Otherwise fully relies on dpctl.tensor implementation for acos() function. - - """ - # dpctl.tensor only works with usm_ndarray - x1_usm = dpnp.get_usm_ndarray(x) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = acos_func(x1_usm, out=out_usm, order=order) - return _get_result(res_usm, out=out) - - -_acosh_docstring = """ -acosh(x, out=None, order='K') - -Computes hyperbolic inverse cosine for each element `x_i` for input array `x`. - -Args: - x (dpnp.ndarray): - Input array, expected to have numeric data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Return: - dpnp.ndarray: - An array containing the element-wise inverse hyperbolic cosine. - The data type of the returned array is determined by - the Type Promotion Rules. -""" - -acosh_func = _make_unary_func( - "arccosh", dpt.acosh, _acosh_docstring, vmi._mkl_acosh_to_call, vmi._acosh -) - - -def dpnp_acosh(x, out=None, order="K"): - """ - Invokes acosh() function from pybind11 extension of OneMKL VM if possible. - - Otherwise fully relies on dpctl.tensor implementation for acosh() function. - - """ - # dpctl.tensor only works with usm_ndarray - x1_usm = dpnp.get_usm_ndarray(x) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = acosh_func(x1_usm, out=out_usm, order=order) - return _get_result(res_usm, out=out) - - -_add_docstring = """ -add(x1, x2, out=None, order="K") - -Calculates the sum for each element `x1_i` of the input array `x1` with -the respective element `x2_i` of the input array `x2`. - -Args: - x1 (dpnp.ndarray): - First input array, expected to have numeric data type. - x2 (dpnp.ndarray): - Second input array, also expected to have numeric data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C","F","A","K", None, optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Returns: - dpnp.ndarray: - an array containing the result of element-wise addition. The data type - of the returned array is determined by the Type Promotion Rules. -""" - -add_func = _make_binary_func( - "add", dpt.add, _add_docstring, vmi._mkl_add_to_call, vmi._add -) - - -def dpnp_add(x1, x2, out=None, order="K"): - """ - Invokes add() function from pybind11 extension of OneMKL VM if possible. - - Otherwise fully relies on dpctl.tensor implementation for add() function. - """ - - # dpctl.tensor only works with usm_ndarray or scalar - x1_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x1) - x2_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x2) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = add_func( - x1_usm_or_scalar, x2_usm_or_scalar, out=out_usm, order=order - ) - return _get_result(res_usm, out=out) - - -_angle_docstring = """ -angle(x, out=None, order="K") - -Computes the phase angle (also called the argument) of each element `x_i` for -input array `x`. - -Args: - x (dpnp.ndarray): - Input array, expected to have a complex-valued floating-point data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Returns: - dpnp.ndarray: - An array containing the element-wise phase angles. - The returned array has a floating-point data type determined - by the Type Promotion Rules. -""" - -angle_func = _make_unary_func("angle", dpt.angle, _angle_docstring) - - -def dpnp_angle(x, out=None, order="K"): - """Invokes angle() from dpctl.tensor implementation for angle() function.""" - - # dpctl.tensor only works with usm_ndarray - x1_usm = dpnp.get_usm_ndarray(x) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = angle_func(x1_usm, out=out_usm, order=order) - return _get_result(res_usm, out=out) - - -_asin_docstring = """ -asin(x, out=None, order='K') - -Computes inverse sine for each element `x_i` for input array `x`. - -Args: - x (dpnp.ndarray): - Input array, expected to have numeric data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Return: - 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. -""" - -asin_func = _make_unary_func( - "arcsin", dpt.asin, _asin_docstring, vmi._mkl_asin_to_call, vmi._asin -) - - -def dpnp_asin(x, out=None, order="K"): - """ - Invokes asin() function from pybind11 extension of OneMKL VM if possible. - - Otherwise fully relies on dpctl.tensor implementation for asin() function. - - """ - # dpctl.tensor only works with usm_ndarray - x1_usm = dpnp.get_usm_ndarray(x) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = asin_func(x1_usm, out=out_usm, order=order) - return _get_result(res_usm, out=out) - - -_asinh_docstring = """ -asinh(x, out=None, order='K') - -Computes inverse hyperbolic sine for each element `x_i` for input array `x`. - -Args: - x (dpnp.ndarray): - Input array, expected to have numeric data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type.. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Return: - 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. -""" - -asinh_func = _make_unary_func( - "arcsinh", dpt.asinh, _asinh_docstring, vmi._mkl_asinh_to_call, vmi._asinh -) - - -def dpnp_asinh(x, out=None, order="K"): - """ - Invokes asinh() function from pybind11 extension of OneMKL VM if possible. - - Otherwise fully relies on dpctl.tensor implementation for asinh() function. - - """ - # dpctl.tensor only works with usm_ndarray - x1_usm = dpnp.get_usm_ndarray(x) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = asinh_func(x1_usm, out=out_usm, order=order) - return _get_result(res_usm, out=out) - - -_atan_docstring = """ -atan(x, out=None, order='K') - -Computes inverse tangent for each element `x_i` for input array `x`. - -Args: - x (dpnp.ndarray): - Input array, expected to have numeric data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type.. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Return: - 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. -""" - -atan_func = _make_unary_func( - "arctan", dpt.atan, _atan_docstring, vmi._mkl_atan_to_call, vmi._atan -) - - -def dpnp_atan(x, out=None, order="K"): - """ - Invokes atan() function from pybind11 extension of OneMKL VM if possible. - - Otherwise fully relies on dpctl.tensor implementation for atan() function. - - """ - # dpctl.tensor only works with usm_ndarray - x1_usm = dpnp.get_usm_ndarray(x) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = atan_func(x1_usm, out=out_usm, order=order) - return _get_result(res_usm, out=out) - - -_atan2_docstring = """ -atan2(x1, x2, out=None, order="K") - -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. - -Args: - x1 (dpnp.ndarray): - First input array, expected to have a real-valued floating-point - data type. - x2 (dpnp.ndarray): - Second input array, also expected to have a real-valued - floating-point data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C","F","A","K", None, optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Returns: - 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. -""" - -atan2_func = _make_binary_func( - "arctan2", dpt.atan2, _atan2_docstring, vmi._mkl_atan2_to_call, vmi._atan2 -) - - -def dpnp_atan2(x1, x2, out=None, order="K"): - """ - Invokes atan2() function from pybind11 extension of OneMKL VM if possible. - - Otherwise fully relies on dpctl.tensor implementation for atan2() function. - """ - - # dpctl.tensor only works with usm_ndarray or scalar - x1_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x1) - x2_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x2) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = atan2_func( - x1_usm_or_scalar, x2_usm_or_scalar, out=out_usm, order=order - ) - return _get_result(res_usm, out=out) - - -_atanh_docstring = """ -atanh(x, out=None, order='K') - -Computes hyperbolic inverse tangent for each element `x_i` for input array `x`. - -Args: - x (dpnp.ndarray): - Input array, expected to have numeric data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Return: - 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. -""" - -atanh_func = _make_unary_func( - "arctanh", dpt.atanh, _atanh_docstring, vmi._mkl_atanh_to_call, vmi._atanh -) - - -def dpnp_atanh(x, out=None, order="K"): - """ - Invokes atanh() function from pybind11 extension of OneMKL VM if possible. - - Otherwise fully relies on dpctl.tensor implementation for atanh() function. - - """ - # dpctl.tensor only works with usm_ndarray - x1_usm = dpnp.get_usm_ndarray(x) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = atanh_func(x1_usm, out=out_usm, order=order) - return _get_result(res_usm, out=out) - - -_bitwise_and_docstring = """ -bitwise_and(x1, x2, out=None, order='K') - -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`. - -Args: - x1 (dpnp.ndarray): - First input array, expected to have integer or boolean data type. - x2 (dpnp.ndarray): - Second input array, also expected to have integer or boolean data - type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Returns: - dpnp.ndarray: - An array containing the element-wise results. The data type - of the returned array is determined by the Type Promotion Rules. -""" - -bitwise_and_func = _make_binary_func( - "bitwise_and", dpt.bitwise_and, _bitwise_and_docstring -) - - -def dpnp_bitwise_and(x1, x2, out=None, order="K"): - """Invokes bitwise_and() from dpctl.tensor implementation for bitwise_and() function.""" - - # dpctl.tensor only works with usm_ndarray or scalar - x1_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x1) - x2_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x2) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = bitwise_and_func( - x1_usm_or_scalar, x2_usm_or_scalar, out=out_usm, order=order - ) - return _get_result(res_usm, out=out) - - -_bitwise_or_docstring = """ -bitwise_or(x1, x2, out=None, order='K') - -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`. - -Args: - x1 (dpnp.ndarray): - First input array, expected to have integer or boolean data type. - x2 (dpnp.ndarray): - Second input array, also expected to have integer or boolean data - type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Returns: - dpnp.ndarray: - An array containing the element-wise results. The data type - of the returned array is determined by the Type Promotion Rules. -""" - -bitwise_or_func = _make_binary_func( - "bitwise_or", dpt.bitwise_or, _bitwise_or_docstring -) - - -def dpnp_bitwise_or(x1, x2, out=None, order="K"): - """Invokes bitwise_or() from dpctl.tensor implementation for bitwise_or() function.""" - - # dpctl.tensor only works with usm_ndarray or scalar - x1_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x1) - x2_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x2) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = bitwise_or_func( - x1_usm_or_scalar, x2_usm_or_scalar, out=out_usm, order=order - ) - return _get_result(res_usm, out=out) - - -_bitwise_xor_docstring = """ -bitwise_xor(x1, x2, out=None, order='K') - -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`. - -Args: - x1 (dpnp.ndarray): - First input array, expected to have integer or boolean data type. - x2 (dpnp.ndarray): - Second input array, also expected to have integer or boolean data - type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Returns: - dpnp.ndarray: - An array containing the element-wise results. The data type - of the returned array is determined by the Type Promotion Rules. -""" - -bitwise_xor_func = _make_binary_func( - "bitwise_xor", dpt.bitwise_xor, _bitwise_xor_docstring -) - - -def dpnp_bitwise_xor(x1, x2, out=None, order="K"): - """Invokes bitwise_xor() from dpctl.tensor implementation for bitwise_xor() function.""" - - # dpctl.tensor only works with usm_ndarray or scalar - x1_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x1) - x2_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x2) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = bitwise_xor_func( - x1_usm_or_scalar, x2_usm_or_scalar, out=out_usm, order=order - ) - return _get_result(res_usm, out=out) - - -_cbrt_docstring = """ -cbrt(x, out=None, order='K') - -Returns the cbrting for each element `x_i` for input array `x`. -The cbrt of the scalar `x` is the smallest integer `i`, such that `i >= x`. - -Args: - x (dpnp.ndarray): - Input array, expected to have a real-valued data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Return: - dpnp.ndarray: - An array containing the element-wise cbrting of input array. - The returned array has the same data type as `x`. -""" - -cbrt_func = _make_unary_func( - "cbrt", dpt.cbrt, _cbrt_docstring, vmi._mkl_cbrt_to_call, vmi._cbrt -) - - -def dpnp_cbrt(x, out=None, order="K"): - """ - Invokes cbrt() function from pybind11 extension of OneMKL VM if possible. - - Otherwise fully relies on dpctl.tensor implementation for cbrt() function. - """ - # dpctl.tensor only works with usm_ndarray - x1_usm = dpnp.get_usm_ndarray(x) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = cbrt_func(x1_usm, out=out_usm, order=order) - return _get_result(res_usm, out=out) - - -_ceil_docstring = """ -ceil(x, out=None, order='K') - -Returns the ceiling for each element `x_i` for input array `x`. -The ceil of the scalar `x` is the smallest integer `i`, such that `i >= x`. - -Args: - x (dpnp.ndarray): - Input array, expected to have a real-valued data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Return: - dpnp.ndarray: - An array containing the element-wise ceiling of input array. - The returned array has the same data type as `x`. -""" - -ceil_func = _make_unary_func( - "ceil", dpt.ceil, _ceil_docstring, vmi._mkl_ceil_to_call, vmi._ceil -) - - -def dpnp_ceil(x, out=None, order="K"): - """ - Invokes ceil() function from pybind11 extension of OneMKL VM if possible. - - Otherwise fully relies on dpctl.tensor implementation for ceil() function. - """ - # dpctl.tensor only works with usm_ndarray - x1_usm = dpnp.get_usm_ndarray(x) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = ceil_func(x1_usm, out=out_usm, order=order) - return _get_result(res_usm, out=out) - - -_conj_docstring = """ -conj(x, out=None, order='K') - -Computes conjugate for each element `x_i` for input array `x`. - -Args: - x (dpnp.ndarray): - Input array, expected to have numeric data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Return: - dpnp.ndarray: - An array containing the element-wise conjugate. - The returned array has the same data type as `x`. -""" - -conj_func = _make_unary_func( - "conj", dpt.conj, _conj_docstring, vmi._mkl_conj_to_call, vmi._conj -) - - -def dpnp_conj(x, out=None, order="K"): - """ - Invokes conj() function from pybind11 extension of OneMKL VM if possible. - - Otherwise fully relies on dpctl.tensor implementation for conj() function. - """ - # dpctl.tensor only works with usm_ndarray - x1_usm = dpnp.get_usm_ndarray(x) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) + result_type_resolver_fn, + unary_dp_impl_fn, + docs, + ): + super().__init__( + name, + result_type_resolver_fn, + unary_dp_impl_fn, + docs, + ) - res_usm = conj_func(x1_usm, out=out_usm, order=order) - return _get_result(res_usm, out=out) + def __call__(self, x, deg=False): + res = super().__call__(x) + if deg is True: + res = res * (180 / dpnp.pi) + return res -_copysign_docstring = """ -copysign(x1, x2, out=None, order='K') +class DPNPReal(DPNPUnaryFunc): + """Class that implements dpnp.real unary element-wise functions.""" -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`. + def __init__( + self, + name, + result_type_resolver_fn, + unary_dp_impl_fn, + docs, + ): + super().__init__( + name, + result_type_resolver_fn, + unary_dp_impl_fn, + docs, + ) -Args: - x1 (dpnp.ndarray): - First input array, expected to have a real floating-point data type. - x2 (dpnp.ndarray): - Second input array, also expected to have a real floating-point data - type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Returns: - dpnp.ndarray: - An array containing the element-wise results. The data type - of the returned array is determined by the Type Promotion Rules. -""" + def __call__(self, x): + if numpy.iscomplexobj(x): + return super().__call__(x) + return x -copysign_func = _make_binary_func("copysign", dpt.copysign, _copysign_docstring) +class DPNPRound(DPNPUnaryFunc): + """Class that implements dpnp.round unary element-wise functions.""" -def dpnp_copysign(x1, x2, out=None, order="K"): - """Invokes copysign() from dpctl.tensor implementation for copysign() function.""" + def __init__( + self, + name, + result_type_resolver_fn, + unary_dp_impl_fn, + docs, + mkl_fn_to_call=None, + mkl_impl_fn=None, + ): + super().__init__( + name, + result_type_resolver_fn, + unary_dp_impl_fn, + docs, + mkl_fn_to_call=mkl_fn_to_call, + mkl_impl_fn=mkl_impl_fn, + ) - # dpctl.tensor only works with usm_ndarray or scalar - x1_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x1) - x2_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x2) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) + def __call__(self, x, decimals=0, out=None, dtype=None): + if decimals != 0: + if dpnp.issubdtype(x.dtype, dpnp.integer) and dtype is None: + dtype = x.dtype + res = dpnp.true_divide( + dpnp.rint(x * 10**decimals, out=out), 10**decimals, out=out + ) + if dtype is not None: + res = res.astype(dtype) + return res + else: + return super().__call__(x, out=out, dtype=dtype) - res_usm = copysign_func( - x1_usm_or_scalar, x2_usm_or_scalar, out=out_usm, order=order - ) - return _get_result(res_usm, out=out) +def acceptance_fn_negative(arg_dtype, buf_dt, res_dt, sycl_dev): + # negative is not defined for boolean data type + if arg_dtype.char == "?": + raise TypeError( + "The `negative` function, the `-` operator, is not supported " + "for inputs of data type bool, use the `~` operator or the " + "`logical_not` function instead" + ) + else: + return True -_cos_docstring = """ -cos(x, out=None, order='K') -Computes cosine for each element `x_i` for input array `x`. +def acceptance_fn_positive(arg_dtype, buf_dt, res_dt, sycl_dev): + # positive is not defined for boolean data type + if arg_dtype.char == "?": + raise TypeError( + "The `positive` function is not supported for inputs of data type " + "bool" + ) + else: + return True -Args: - x (dpnp.ndarray): - Input array, expected to have numeric data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Return: - dpnp.ndarray: - An array containing the element-wise cosine. The data type - of the returned array is determined by the Type Promotion Rules. -""" -cos_func = _make_unary_func( - "cos", dpt.cos, _cos_docstring, vmi._mkl_cos_to_call, vmi._cos -) +def acceptance_fn_sign(arg_dtype, buf_dt, res_dt, sycl_dev): + # sign is not defined for boolean data type + if arg_dtype.char == "?": + raise TypeError( + "The `sign` function is not supported for inputs of data type bool" + ) + else: + return True -def dpnp_cos(x, out=None, order="K"): - """ - Invokes cos() function from pybind11 extension of OneMKL VM if possible. - - Otherwise fully relies on dpctl.tensor implementation for cos() function. - - """ - # dpctl.tensor only works with usm_ndarray - x1_usm = dpnp.get_usm_ndarray(x) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = cos_func(x1_usm, out=out_usm, order=order) - return _get_result(res_usm, out=out) - - -_cosh_docstring = """ -cosh(x, out=None, order='K') - -Computes hyperbolic cosine for each element `x_i` for input array `x`. - -Args: - x (dpnp.ndarray): - Input array, expected to have numeric data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Return: - dpnp.ndarray: - An array containing the element-wise hyperbolic cosine. The data type - of the returned array is determined by the Type Promotion Rules. -""" - -cosh_func = _make_unary_func( - "cosh", dpt.cosh, _cosh_docstring, vmi._mkl_cosh_to_call, vmi._cosh -) - - -def dpnp_cosh(x, out=None, order="K"): - """ - Invokes cosh() function from pybind11 extension of OneMKL VM if possible. - - Otherwise fully relies on dpctl.tensor implementation for cosh() function. - - """ - # dpctl.tensor only works with usm_ndarray - x1_usm = dpnp.get_usm_ndarray(x) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = cosh_func(x1_usm, out=out_usm, order=order) - return _get_result(res_usm, out=out) - - -_divide_docstring = """ -divide(x1, x2, out=None, order="K") - -Calculates the ratio for each element `x1_i` of the input array `x1` with -the respective element `x2_i` of the input array `x2`. - -Args: - x1 (dpnp.ndarray): - First input array, expected to have numeric data type. - x2 (dpnp.ndarray): - Second input array, also expected to have numeric data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C","F","A","K", None, optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Returns: - dpnp.ndarray: - an array containing the result of element-wise division. The data type - of the returned array is determined by the Type Promotion Rules. -""" - -divide_func = _make_binary_func( - "divide", dpt.divide, _divide_docstring, vmi._mkl_div_to_call, vmi._div -) - - -def dpnp_divide(x1, x2, out=None, order="K"): - """ - Invokes div() function from pybind11 extension of OneMKL VM if possible. - - Otherwise fully relies on dpctl.tensor implementation for divide() function. - """ - - # dpctl.tensor only works with usm_ndarray or scalar - x1_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x1) - x2_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x2) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = divide_func( - x1_usm_or_scalar, x2_usm_or_scalar, out=out_usm, order=order - ) - return _get_result(res_usm, out=out) - - -_equal_docstring = """ -equal(x1, x2, out=None, order="K") - -Calculates equality results for each element `x1_i` of -the input array `x1` the respective element `x2_i` of the input array `x2`. - -Args: - x1 (dpnp.ndarray): - First input array, expected to have numeric data type. - x2 (dpnp.ndarray): - Second input array, also expected to have numeric data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array have the correct shape and the expected data type. - order ("C","F","A","K", None, optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Returns: - dpnp.ndarray: - an array containing the result of element-wise equality comparison. - The data type of the returned array is determined by the Type Promotion Rules. -""" - -equal_func = _make_binary_func("equal", dpt.equal, _equal_docstring) - - -def dpnp_equal(x1, x2, out=None, order="K"): - """Invokes equal() from dpctl.tensor implementation for equal() function.""" - - # dpctl.tensor only works with usm_ndarray or scalar - x1_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x1) - x2_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x2) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = equal_func( - x1_usm_or_scalar, x2_usm_or_scalar, out=out_usm, order=order - ) - return _get_result(res_usm, out=out) - - -_exp_docstring = """ -exp(x, out=None, order='K') - -Computes the exponential for each element `x_i` of input array `x`. - -Args: - x (dpnp.ndarray): - Input array, expected to have numeric data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Return: - dpnp.ndarray: - An array containing the element-wise exponential of `x`. - The data type of the returned array is determined by - the Type Promotion Rules. -""" - -exp_func = _make_unary_func( - "exp", dpt.exp, _exp_docstring, vmi._mkl_exp_to_call, vmi._exp -) - - -def dpnp_exp(x, out=None, order="K"): - """ - Invokes exp() function from pybind11 extension of OneMKL VM if possible. - - Otherwise fully relies on dpctl.tensor implementation for exp() function. - """ - - # dpctl.tensor only works with usm_ndarray - x1_usm = dpnp.get_usm_ndarray(x) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = exp_func(x1_usm, out=out_usm, order=order) - return _get_result(res_usm, out=out) - - -_exp2_docstring = """ -exp2(x, out=None, order='K') - -Computes the base-2 exponential for each element `x_i` for input array `x`. - -Args: - x (dpnp.ndarray): - Input array, expected to have a floating-point data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Return: - dpnp.ndarray: - An array containing the element-wise base-2 exponentials. - The data type of the returned array is determined by - the Type Promotion Rules. -""" - -exp2_func = _make_unary_func( - "exp2", dpt.exp2, _exp2_docstring, vmi._mkl_exp2_to_call, vmi._exp2 -) - - -def dpnp_exp2(x, out=None, order="K"): - """ - Invokes exp2() function from pybind11 extension of OneMKL VM if possible. - - Otherwise fully relies on dpctl.tensor implementation for exp2() function. - """ - - # dpctl.tensor only works with usm_ndarray - x1_usm = dpnp.get_usm_ndarray(x) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = exp2_func(x1_usm, out=out_usm, order=order) - return _get_result(res_usm, out=out) - - -_expm1_docstring = """ -expm1(x, out=None, order='K') - -Computes the exponential 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`. - -Args: - x (dpnp.ndarray): - Input array, expected to have numeric data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Return: - 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. -""" - -expm1_func = _make_unary_func( - "expm1", dpt.expm1, _expm1_docstring, vmi._mkl_expm1_to_call, vmi._expm1 -) - - -def dpnp_expm1(x, out=None, order="K"): - """ - Invokes expm1() function from pybind11 extension of OneMKL VM if possible. - - Otherwise fully relies on dpctl.tensor implementation for expm1() function. - """ - - # dpctl.tensor only works with usm_ndarray - x1_usm = dpnp.get_usm_ndarray(x) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = expm1_func(x1_usm, out=out_usm, order=order) - return _get_result(res_usm, out=out) - - -_floor_docstring = """ -floor(x, out=None, order='K') - -Returns the floor for each element `x_i` for input array `x`. -The floor of the scalar `x` is the largest integer `i`, such that `i <= x`. - -Args: - x (dpnp.ndarray): - Input array, expected to have a real-valued data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Return: - dpnp.ndarray: - An array containing the element-wise floor of input array. - The returned array has the same data type as `x`. -""" - -floor_func = _make_unary_func( - "floor", dpt.floor, _floor_docstring, vmi._mkl_floor_to_call, vmi._floor -) - - -def dpnp_floor(x, out=None, order="K"): - """ - Invokes floor() function from pybind11 extension of OneMKL VM if possible. - - Otherwise fully relies on dpctl.tensor implementation for floor() function. - """ - # dpctl.tensor only works with usm_ndarray - x1_usm = dpnp.get_usm_ndarray(x) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = floor_func(x1_usm, out=out_usm, order=order) - return _get_result(res_usm, out=out) - - -_floor_divide_docstring = """ -floor_divide(x1, x2, out=None, order="K") - -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. - -Args: - x1 (dpnp.ndarray): - First input array, expected to have numeric data type. - x2 (dpnp.ndarray): - Second input array, also expected to have numeric data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C","F","A","K", None, optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Returns: - dpnp.ndarray: - an array containing the result of element-wise floor division. - The data type of the returned array is determined by the Type - Promotion Rules -""" - -floor_divide_func = _make_binary_func( - "floor_divide", dpt.floor_divide, _floor_divide_docstring -) - - -def dpnp_floor_divide(x1, x2, out=None, order="K"): - """Invokes floor_divide() from dpctl.tensor implementation for floor_divide() function.""" - - # dpctl.tensor only works with usm_ndarray or scalar - x1_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x1) - x2_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x2) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = floor_divide_func( - x1_usm_or_scalar, x2_usm_or_scalar, out=out_usm, order=order - ) - return _get_result(res_usm, out=out) - - -_greater_docstring = """ -greater(x1, x2, out=None, order="K") - -Calculates the greater-than results for each element `x1_i` of -the input array `x1` the respective element `x2_i` of the input array `x2`. - -Args: - x1 (dpnp.ndarray): - First input array, expected to have numeric data type. - x2 (dpnp.ndarray): - Second input array, also expected to have numeric data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C","F","A","K", None, optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Returns: - dpnp.ndarray: - an array containing the result of element-wise greater-than comparison. - The data type of the returned array is determined by the Type Promotion Rules. -""" - -greater_func = _make_binary_func("greater", dpt.greater, _greater_docstring) - - -def dpnp_greater(x1, x2, out=None, order="K"): - """Invokes greater() from dpctl.tensor implementation for greater() function.""" - - # dpctl.tensor only works with usm_ndarray or scalar - x1_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x1) - x2_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x2) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = greater_func( - x1_usm_or_scalar, x2_usm_or_scalar, out=out_usm, order=order - ) - return _get_result(res_usm, out=out) - - -_greater_equal_docstring = """ -greater_equal(x1, x2, out=None, order="K") - -Calculates the greater-than or equal-to results for each element `x1_i` of -the input array `x1` the respective element `x2_i` of the input array `x2`. - -Args: - x1 (dpnp.ndarray): - First input array, expected to have numeric data type. - x2 (dpnp.ndarray): - Second input array, also expected to have numeric data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C","F","A","K", None, optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Returns: - dpnp.ndarray: - an array containing the result of element-wise greater-than or equal-to comparison. - The data type of the returned array is determined by the Type Promotion Rules. -""" - -greater_equal_func = _make_binary_func( - "greater_equal", dpt.greater_equal, _greater_equal_docstring -) - - -def dpnp_greater_equal(x1, x2, out=None, order="K"): - """Invokes greater_equal() from dpctl.tensor implementation for greater_equal() function.""" - - # dpctl.tensor only works with usm_ndarray or scalar - x1_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x1) - x2_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x2) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = greater_equal_func( - x1_usm_or_scalar, x2_usm_or_scalar, out=out_usm, order=order - ) - return _get_result(res_usm, out=out) - - -_hypot_docstring = """ -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`. - -Args: - x1 (dpnp.ndarray): - First input array, expected to have a real-valued data type. - x2 (dpnp.ndarray): - Second input array, also expected to have a real-valued data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C","F","A","K", None, optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Returns: - dpnp.ndarray: - An array containing the element-wise hypotenuse. The data type - of the returned array is determined by the Type Promotion Rules. -""" - -hypot_func = _make_binary_func( - "hypot", dpt.hypot, _hypot_docstring, vmi._mkl_hypot_to_call, vmi._hypot -) - - -def dpnp_hypot(x1, x2, out=None, order="K"): - """ - Invokes hypot() function from pybind11 extension of OneMKL VM if possible. - - Otherwise fully relies on dpctl.tensor implementation for hypot() function. - """ - - # dpctl.tensor only works with usm_ndarray or scalar - x1_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x1) - x2_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x2) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = hypot_func( - x1_usm_or_scalar, x2_usm_or_scalar, out=out_usm, order=order - ) - return _get_result(res_usm, out=out) - - -_imag_docstring = """ -imag(x, out=None, order="K") - -Computes imaginary part of each element `x_i` for input array `x`. - -Args: - x (dpnp.ndarray): - Input array, expected to have numeric data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Returns: - 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 - 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. -""" - -imag_func = _make_unary_func("imag", dpt.imag, _imag_docstring) - - -def dpnp_imag(x, out=None, order="K"): - """Invokes imag() from dpctl.tensor implementation for imag() function.""" - - # dpctl.tensor only works with usm_ndarray - x1_usm = dpnp.get_usm_ndarray(x) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = imag_func(x1_usm, out=out_usm, order=order) - return _get_result(res_usm, out=out) - - -_invert_docstring = """ -invert(x, out=None, order='K') - -Inverts (flips) each bit for each element `x_i` of the input array `x`. - -Args: - x (dpnp.ndarray): - Input array, expected to have integer or boolean data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Return: - dpnp.ndarray: - An array containing the element-wise results. - The data type of the returned array is same as the data type of the - input array. -""" - -invert_func = _make_unary_func("invert", dpt.bitwise_invert, _invert_docstring) - - -def dpnp_invert(x, out=None, order="K"): - """Invokes bitwise_invert() from dpctl.tensor implementation for invert() function.""" - - # dpctl.tensor only works with usm_ndarray or scalar - x_usm = dpnp.get_usm_ndarray(x) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = invert_func(x_usm, out=out_usm, order=order) - return _get_result(res_usm, out=out) - - -_isfinite_docstring = """ -isfinite(x, out=None, order="K") - -Checks if each element of input array is a finite number. - -Args: - x (dpnp.ndarray): - Input array, expected to have numeric data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Returns: - dpnp.ndarray: - An array which is True where `x` is not positive infinity, - negative infinity, or NaN, False otherwise. - The data type of the returned array is `bool`. -""" - -isfinite_func = _make_unary_func("isfinite", dpt.isfinite, _isfinite_docstring) - - -def dpnp_isfinite(x, out=None, order="K"): - """Invokes isfinite() from dpctl.tensor implementation for isfinite() function.""" - - # dpctl.tensor only works with usm_ndarray - x1_usm = dpnp.get_usm_ndarray(x) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = isfinite_func(x1_usm, out=out_usm, order=order) - return _get_result(res_usm, out=out) - - -_isinf_docstring = """ -isinf(x, out=None, order="K") - -Checks if each element of input array is an infinity. - -Args: - x (dpnp.ndarray): - Input array, expected to have numeric data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Returns: - dpnp.ndarray: - An array which is True where `x` is positive or negative infinity, - False otherwise. The data type of the returned array is `bool`. -""" - -isinf_func = _make_unary_func("isinf", dpt.isinf, _isinf_docstring) - - -def dpnp_isinf(x, out=None, order="K"): - """Invokes isinf() from dpctl.tensor implementation for isinf() function.""" - - # dpctl.tensor only works with usm_ndarray - x1_usm = dpnp.get_usm_ndarray(x) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = isinf_func(x1_usm, out=out_usm, order=order) - return _get_result(res_usm, out=out) - - -_isnan_docstring = """ -isnan(x, out=None, order="K") - -Checks if each element of an input array is a NaN. - -Args: - x (dpnp.ndarray): - Input array, expected to have numeric data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Returns: - dpnp.ndarray: - An array which is True where x is NaN, False otherwise. - The data type of the returned array is `bool`. -""" - -isnan_func = _make_unary_func("isnan", dpt.isnan, _isnan_docstring) - - -def dpnp_isnan(x, out=None, order="K"): - """Invokes isnan() from dpctl.tensor implementation for isnan() function.""" - - # dpctl.tensor only works with usm_ndarray - x1_usm = dpnp.get_usm_ndarray(x) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = isnan_func(x1_usm, out=out_usm, order=order) - return _get_result(res_usm, out=out) - - -_left_shift_docstring = """ -left_shift(x1, x2, out=None, order='K') - -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`. - -Args: - x1 (dpnp.ndarray): - First input array, expected to have integer data type. - x2 (dpnp.ndarray): - Second input array, also expected to have integer data type. - Each element must be greater than or equal to 0. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Returns: - dpnp.ndarray: - An array containing the element-wise results. The data type - of the returned array is determined by the Type Promotion Rules. -""" - -left_shift_func = _make_binary_func( - "left_shift", dpt.bitwise_left_shift, _left_shift_docstring -) - - -def dpnp_left_shift(x1, x2, out=None, order="K"): - """Invokes bitwise_left_shift() from dpctl.tensor implementation for left_shift() function.""" - - # dpctl.tensor only works with usm_ndarray or scalar - x1_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x1) - x2_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x2) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = left_shift_func( - x1_usm_or_scalar, x2_usm_or_scalar, out=out_usm, order=order - ) - return _get_result(res_usm, out=out) - - -_less_docstring = """ -less(x1, x2, out=None, order="K") - -Calculates the less-than results for each element `x1_i` of -the input array `x1` the respective element `x2_i` of the input array `x2`. - -Args: - x1 (dpnp.ndarray): - First input array, expected to have numeric data type. - x2 (dpnp.ndarray): - Second input array, also expected to have numeric data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C","F","A","K", None, optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Returns: - dpnp.ndarray: - an array containing the result of element-wise less-than comparison. - The data type of the returned array is determined by the Type Promotion Rules. -""" - -less_func = _make_binary_func("less", dpt.less, _less_docstring) - - -def dpnp_less(x1, x2, out=None, order="K"): - """Invokes less() from dpctl.tensor implementation for less() function.""" - - # dpctl.tensor only works with usm_ndarray or scalar - x1_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x1) - x2_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x2) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = less_func( - x1_usm_or_scalar, x2_usm_or_scalar, out=out_usm, order=order - ) - return _get_result(res_usm, out=out) - - -_less_equal_docstring = """ -less_equal(x1, x2, out=None, order="K") - -Calculates the less-than or equal-to results for each element `x1_i` of -the input array `x1` the respective element `x2_i` of the input array `x2`. - -Args: - x1 (dpnp.ndarray): - First input array, expected to have numeric data type. - x2 (dpnp.ndarray): - Second input array, also expected to have numeric data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C","F","A","K", None, optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Returns: - dpnp.ndarray: - An array containing the result of element-wise less-than or equal-to comparison. - The data type of the returned array is determined by the Type Promotion Rules. -""" - -less_equal_func = _make_binary_func( - "less_equal", dpt.less_equal, _less_equal_docstring -) - - -def dpnp_less_equal(x1, x2, out=None, order="K"): - """Invokes less_equal() from dpctl.tensor implementation for less_equal() function.""" - - # dpctl.tensor only works with usm_ndarray or scalar - x1_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x1) - x2_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x2) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = less_equal_func( - x1_usm_or_scalar, x2_usm_or_scalar, out=out_usm, order=order - ) - return _get_result(res_usm, out=out) - - -_log_docstring = """ -log(x, out=None, order='K') - -Computes the natural logarithm element-wise. - -Args: - x (dpnp.ndarray): - Input array, expected to have numeric data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Return: - 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. -""" - -log_func = _make_unary_func( - "log", dpt.log, _log_docstring, vmi._mkl_ln_to_call, vmi._ln -) - - -def dpnp_log(x, out=None, order="K"): - """ - Invokes log() function from pybind11 extension of OneMKL VM if possible. - - Otherwise fully relies on dpctl.tensor implementation for log() function. - """ - - # dpctl.tensor only works with usm_ndarray - x1_usm = dpnp.get_usm_ndarray(x) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = log_func(x1_usm, out=out_usm, order=order) - return _get_result(res_usm, out=out) - - -_log10_docstring = """ -log10(x, out=None, order='K') - -Computes the base-10 logarithm for each element `x_i` of input array `x`. - -Args: - x (dpnp.ndarray): - Input array, expected to have numeric data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Return: - dpnp.ndarray: - An array containing the base-10 logarithm of `x`. - The data type of the returned array is determined by the - Type Promotion Rules. -""" - -log10_func = _make_unary_func( - "log10", dpt.log10, _log10_docstring, vmi._mkl_log10_to_call, vmi._log10 -) - - -def dpnp_log10(x, out=None, order="K"): - """ - Invokes log10() function from pybind11 extension of OneMKL VM if possible. - - Otherwise fully relies on dpctl.tensor implementation for log10() function. - """ - - # dpctl.tensor only works with usm_ndarray - x1_usm = dpnp.get_usm_ndarray(x) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = log10_func(x1_usm, out=out_usm, order=order) - return _get_result(res_usm, out=out) - - -_log1p_docstring = """ -log1p(x, out=None, order='K') - -Computes an approximation of `log(1+x)` element-wise. - -Args: - x (dpnp.ndarray): - Input array, expected to have numeric data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Return: - dpnp.ndarray: - An array containing the element-wise `log(1+x)` values. The data type - of the returned array is determined by the Type Promotion Rules. -""" - -log1p_func = _make_unary_func( - "log1p", dpt.log1p, _log1p_docstring, vmi._mkl_log1p_to_call, vmi._log1p -) - - -def dpnp_log1p(x, out=None, order="K"): - """ - Invokes log1p() function from pybind11 extension of OneMKL VM if possible. - - Otherwise fully relies on dpctl.tensor implementation for log1p() function. - """ - - # dpctl.tensor only works with usm_ndarray - x1_usm = dpnp.get_usm_ndarray(x) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = log1p_func(x1_usm, out=out_usm, order=order) - return _get_result(res_usm, out=out) - - -_log2_docstring = """ -log2(x, out=None, order='K') - -Computes the base-2 logarithm for each element `x_i` of input array `x`. - -Args: - x (dpnp.ndarray): - Input array, expected to have numeric data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Return: - dpnp.ndarray: - An array containing the base-2 logarithm of `x`. - The data type of the returned array is determined by the - Type Promotion Rules. -""" - -log2_func = _make_unary_func( - "log2", dpt.log2, _log2_docstring, vmi._mkl_log2_to_call, vmi._log2 -) - - -def dpnp_log2(x, out=None, order="K"): - """ - Invokes log2() function from pybind11 extension of OneMKL VM if possible. - - Otherwise fully relies on dpctl.tensor implementation for log2() function. - """ - - # dpctl.tensor only works with usm_ndarray - x1_usm = dpnp.get_usm_ndarray(x) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = log2_func(x1_usm, out=out_usm, order=order) - return _get_result(res_usm, out=out) - - -_logaddexp_docstring = """ -logaddexp(x1, x2, out=None, order="K") - -Calculates the natural logarithm of the sum of exponentiations 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`. - -Args: - x1 (dpnp.ndarray): - First input array, expected to have a real-valued floating-point - data type. - x2 (dpnp.ndarray): - Second input array, also expected to have a real-valued - floating-point data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C","F","A","K", None, optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Returns: - dpnp.ndarray: - An array containing the result of element-wise result. The data type - of the returned array is determined by the Type Promotion Rules. -""" - -logaddexp_func = _make_binary_func( - "logaddexp", dpt.logaddexp, _logaddexp_docstring -) - - -def dpnp_logaddexp(x1, x2, out=None, order="K"): - """Invokes logaddexp() from dpctl.tensor implementation for logaddexp() function.""" - - # dpctl.tensor only works with usm_ndarray or scalar - x1_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x1) - x2_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x2) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = logaddexp_func( - x1_usm_or_scalar, x2_usm_or_scalar, out=out_usm, order=order - ) - return _get_result(res_usm, out=out) - - -_logical_and_docstring = """ -logical_and(x1, x2, out=None, order='K') - -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`. - -Args: - x1 (dpnp.ndarray): - First input array. - x2 (dpnp.ndarray): - Second input array. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Returns: - dpnp.ndarray: - An array containing the element-wise logical AND results. -""" - -logical_and_func = _make_binary_func( - "logical_and", dpt.logical_and, _logical_and_docstring -) - - -def dpnp_logical_and(x1, x2, out=None, order="K"): - """Invokes logical_and() from dpctl.tensor implementation for logical_and() function.""" - - # dpctl.tensor only works with usm_ndarray or scalar - x1_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x1) - x2_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x2) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = logical_and_func( - x1_usm_or_scalar, x2_usm_or_scalar, out=out_usm, order=order - ) - return _get_result(res_usm, out=out) - - -_logical_not_docstring = """ -logical_not(x, out=None, order='K') - -Computes the logical NOT for each element `x_i` of input array `x`. - -Args: - x (dpnp.ndarray): - Input array. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Return: - dpnp.ndarray: - An array containing the element-wise logical NOT results. -""" - -logical_not_func = _make_unary_func( - "logical_not", dpt.logical_not, _logical_not_docstring -) - - -def dpnp_logical_not(x, out=None, order="K"): - """Invokes logical_not() from dpctl.tensor implementation for logical_not() function.""" - - # dpctl.tensor only works with usm_ndarray or scalar - x_usm = dpnp.get_usm_ndarray(x) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = logical_not_func(x_usm, out=out_usm, order=order) - return _get_result(res_usm, out=out) - - -_logical_or_docstring = """ -logical_or(x1, x2, out=None, order='K') - -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`. - -Args: - x1 (dpnp.ndarray): - First input array. - x2 (dpnp.ndarray): - Second input array. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Returns: - dpnp.ndarray: - An array containing the element-wise logical OR results. -""" - -logical_or_func = _make_binary_func( - "logical_or", dpt.logical_or, _logical_or_docstring -) - - -def dpnp_logical_or(x1, x2, out=None, order="K"): - """Invokes logical_or() from dpctl.tensor implementation for logical_or() function.""" - - # dpctl.tensor only works with usm_ndarray or scalar - x1_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x1) - x2_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x2) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = logical_or_func( - x1_usm_or_scalar, x2_usm_or_scalar, out=out_usm, order=order - ) - return _get_result(res_usm, out=out) - - -_logical_xor_docstring = """ -logical_xor(x1, x2, out=None, order='K') - -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`. - -Args: - x1 (dpnp.ndarray): - First input array. - x2 (dpnp.ndarray): - Second input array. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Returns: - dpnp.ndarray: - An array containing the element-wise logical XOR results. -""" - -logical_xor_func = _make_binary_func( - "logical_xor", dpt.logical_xor, _logical_xor_docstring -) - - -def dpnp_logical_xor(x1, x2, out=None, order="K"): - """Invokes logical_xor() from dpctl.tensor implementation for logical_xor() function.""" - - # dpctl.tensor only works with usm_ndarray or scalar - x1_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x1) - x2_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x2) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = logical_xor_func( - x1_usm_or_scalar, x2_usm_or_scalar, out=out_usm, order=order - ) - return _get_result(res_usm, out=out) - - -_maximum_docstring = """ -maximum(x1, x2, out=None, order='K') - -Compares two input arrays `x1` and `x2` and returns -a new array containing the element-wise maxima. - -Args: - x1 (dpnp.ndarray): - First input array, expected to have numeric data type. - x2 (dpnp.ndarray): - Second input array, also expected to have numeric data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Returns: - dpnp.ndarray: - An array containing the element-wise maxima. The data type of - the returned array is determined by the Type Promotion Rules. -""" - -maximum_func = _make_binary_func("maximum", dpt.maximum, _maximum_docstring) - - -def dpnp_maximum(x1, x2, out=None, order="K"): - """Invokes maximum() from dpctl.tensor implementation for maximum() function.""" - - # dpctl.tensor only works with usm_ndarray or scalar - x1_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x1) - x2_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x2) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = maximum_func( - x1_usm_or_scalar, x2_usm_or_scalar, out=out_usm, order=order - ) - return _get_result(res_usm, out=out) - - -_minimum_docstring = """ -minimum(x1, x2, out=None, order='K') - -Compares two input arrays `x1` and `x2` and returns -a new array containing the element-wise minima. - -Args: - x1 (dpnp.ndarray): - First input array, expected to have numeric data type. - x2 (dpnp.ndarray): - Second input array, also expected to have numeric data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Returns: - dpnp.ndarray: - An array containing the element-wise minima. The data type of - the returned array is determined by the Type Promotion Rules. -""" - -minimum_func = _make_binary_func("minimum", dpt.minimum, _minimum_docstring) - - -def dpnp_minimum(x1, x2, out=None, order="K"): - """Invokes minimum() from dpctl.tensor implementation for minimum() function.""" - - # dpctl.tensor only works with usm_ndarray or scalar - x1_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x1) - x2_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x2) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = minimum_func( - x1_usm_or_scalar, x2_usm_or_scalar, out=out_usm, order=order - ) - return _get_result(res_usm, out=out) - - -_multiply_docstring = """ -multiply(x1, x2, out=None, order="K") - -Calculates the product for each element `x1_i` of the input array `x1` -with the respective element `x2_i` of the input array `x2`. - -Args: - x1 (dpnp.ndarray): - First input array, expected to have numeric data type. - x2 (dpnp.ndarray): - Second input array, also expected to have numeric data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C","F","A","K", None, optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Returns: - dpnp.ndarray: - an array containing the result of element-wise multiplication. The data type - of the returned array is determined by the Type Promotion Rules. -""" - -multiply_func = _make_binary_func( - "multiply", - dpt.multiply, - _multiply_docstring, - vmi._mkl_mul_to_call, - vmi._mul, -) - - -def dpnp_multiply(x1, x2, out=None, order="K"): - """ - Invokes mul() function from pybind11 extension of OneMKL VM if possible. - - Otherwise fully relies on dpctl.tensor implementation for multiply() function. - """ - - # dpctl.tensor only works with usm_ndarray or scalar - x1_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x1) - x2_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x2) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = multiply_func( - x1_usm_or_scalar, x2_usm_or_scalar, out=out_usm, order=order - ) - return _get_result(res_usm, out=out) - - -_negative_docstring = """ -negative(x, out=None, order="K") - -Computes the numerical negative for each element `x_i` of input array `x`. - -Args: - x (dpnp.ndarray): - Input array, expected to have numeric data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Returns: - dpnp.ndarray: - An array containing the negative of `x`. -""" - -negative_func = _make_unary_func("negative", dpt.negative, _negative_docstring) - - -def dpnp_negative(x, out=None, order="K"): - """Invokes negative() from dpctl.tensor implementation for negative() function.""" - - # dpctl.tensor only works with usm_ndarray - x1_usm = dpnp.get_usm_ndarray(x) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - # TODO: discuss with dpctl if the check is needed to be moved out of there - if not dpnp.isscalar(x) and x.dtype == dpnp.bool: - raise TypeError( - "DPNP boolean negative, the `-` operator, is not supported, " - "use the `~` operator or the logical_not function instead." - ) - - res_usm = negative_func(x1_usm, out=out_usm, order=order) - return _get_result(res_usm, out=out) - - -_not_equal_docstring = """ -not_equal(x1, x2, out=None, order="K") - -Calculates inequality results for each element `x1_i` of -the input array `x1` the respective element `x2_i` of the input array `x2`. - -Args: - x1 (dpnp.ndarray): - First input array, expected to have numeric data type. - x2 (dpnp.ndarray): - Second input array, also expected to have numeric data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C","F","A","K", None, optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Returns: - dpnp.ndarray: - an array containing the result of element-wise inequality comparison. - The data type of the returned array is determined by the Type Promotion Rules. -""" - -not_equal_func = _make_binary_func( - "not_equal", dpt.not_equal, _not_equal_docstring -) - - -def dpnp_not_equal(x1, x2, out=None, order="K"): - """Invokes not_equal() from dpctl.tensor implementation for not_equal() function.""" - - # dpctl.tensor only works with usm_ndarray or scalar - x1_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x1) - x2_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x2) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = not_equal_func( - x1_usm_or_scalar, x2_usm_or_scalar, out=out_usm, order=order - ) - return _get_result(res_usm, out=out) - - -_positive_docstring = """ -positive(x, out=None, order="K") - -Computes the numerical positive for each element `x_i` of input array `x`. - -Args: - x (dpnp.ndarray): - Input array, expected to have numeric data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Returns: - dpnp.ndarray: - An array containing the positive of `x`. -""" - -positive_func = _make_unary_func("positive", dpt.positive, _positive_docstring) - - -def dpnp_positive(x, out=None, order="K"): - """Invokes positive() from dpctl.tensor implementation for positive() function.""" - - # TODO: discuss with dpctl if the check is needed to be moved there - if not dpnp.isscalar(x) and x.dtype == dpnp.bool: - raise TypeError( - "DPNP boolean positive, the `+` operator, is not supported." - ) - - # dpctl.tensor only works with usm_ndarray - x1_usm = dpnp.get_usm_ndarray(x) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = positive_func(x1_usm, out=out_usm, order=order) - return _get_result(res_usm, out=out) - - -_power_docstring = """ -power(x1, x2, out=None, order="K") - -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`. - -Args: - x1 (dpnp.ndarray): - First input array, expected to have numeric data type. - x2 (dpnp.ndarray): - Second input array, also expected to have numeric data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. Array must have the correct - shape and the expected data type. - order ("C","F","A","K", None, optional): - Output array, if parameter `out` is ``None``. - Default: "K". -Returns: - dpnp.ndarray: - An array containing the result of element-wise of raising each element - to a specified power. - The data type of the returned array is determined by the Type Promotion Rules. -""" - -power_func = _make_binary_func( - "power", dpt.pow, _power_docstring, vmi._mkl_pow_to_call, vmi._pow -) - - -def dpnp_power(x1, x2, out=None, order="K"): - """ - Invokes pow() function from pybind11 extension of OneMKL VM if possible. - - Otherwise fully relies on dpctl.tensor implementation for pow() function. - """ - - # dpctl.tensor only works with usm_ndarray or scalar - x1_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x1) - x2_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x2) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = power_func( - x1_usm_or_scalar, x2_usm_or_scalar, out=out_usm, order=order - ) - return _get_result(res_usm, out=out) - - -_proj_docstring = """ -proj(x, out=None, order="K") - -Computes projection of each element `x_i` for input array `x`. - -Args: - x (dpnp.ndarray): - Input array, expected to have numeric data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Returns: - dpnp.ndarray: - An array containing the element-wise projection. - The returned array has the same data type as `x`. -""" - -proj_func = _make_unary_func("proj", dpt.proj, _proj_docstring) - - -def dpnp_proj(x, out=None, order="K"): - """Invokes proj() from dpctl.tensor implementation for proj() function.""" - - # dpctl.tensor only works with usm_ndarray - x1_usm = dpnp.get_usm_ndarray(x) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = proj_func(x1_usm, out=out_usm, order=order) - return _get_result(res_usm, out=out) - - -_real_docstring = """ -real(x, out=None, order="K") - -Computes real part of each element `x_i` for input array `x`. - -Args: - x (dpnp.ndarray): - Input array, expected to have numeric data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Returns: - 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 - 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. -""" - -real_func = _make_unary_func("real", dpt.real, _real_docstring) - - -def dpnp_real(x, out=None, order="K"): - """Invokes real() from dpctl.tensor implementation for real() function.""" - - # dpctl.tensor only works with usm_ndarray - x1_usm = dpnp.get_usm_ndarray(x) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = real_func(x1_usm, out=out_usm, order=order) - return _get_result(res_usm, out=out) - - -_reciprocal_docstring = """ -reciprocal(x, out=None, order="K") - -Computes the reciprocal of each element `x_i` for input array `x`. - -Args: - x (dpnp.ndarray): - Input array, expected to have a real-valued floating-point data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Returns: - dpnp.ndarray: - An array containing the element-wise reciprocals. - The returned array has a floating-point data type determined - by the Type Promotion Rules. -""" - -reciprocal_func = _make_unary_func( - "reciprocal", dpt.reciprocal, _reciprocal_docstring -) - - -def dpnp_reciprocal(x, out=None, order="K"): - """Invokes reciprocal() from dpctl.tensor implementation for reciprocal() function.""" - - # dpctl.tensor only works with usm_ndarray - x1_usm = dpnp.get_usm_ndarray(x) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = reciprocal_func(x1_usm, out=out_usm, order=order) - return _get_result(res_usm, out=out) - - -_remainder_docstring = """ -remainder(x1, x2, out=None, order='K') - -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`. -This function is equivalent to the Python modulus operator. - -Args: - x1 (dpnp.ndarray): - First input array, expected to have a real-valued data type. - x2 (dpnp.ndarray): - Second input array, also expected to have a real-valued data type. - out ({None, usm_ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Returns: - dpnp.ndarray: - an array containing the element-wise remainders. The data type of - the returned array is determined by the Type Promotion Rules. -""" - -remainder_func = _make_binary_func( - "remainder", dpt.remainder, _remainder_docstring -) - - -def dpnp_remainder(x1, x2, out=None, order="K"): - # dpctl.tensor only works with usm_ndarray or scalar - x1_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x1) - x2_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x2) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = remainder_func( - x1_usm_or_scalar, x2_usm_or_scalar, out=out_usm, order=order - ) - return _get_result(res_usm, out=out) - - -_right_shift_docstring = """ -right_shift(x1, x2, out=None, order='K') - -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`. - -Args: - x1 (dpnp.ndarray): - First input array, expected to have integer data type. - x2 (dpnp.ndarray): - Second input array, also expected to have integer data type. - Each element must be greater than or equal to 0. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Returns: - dpnp.ndarray: - An array containing the element-wise results. The data type - of the returned array is determined by the Type Promotion Rules. -""" - -right_shift_func = _make_binary_func( - "right_shift", dpt.bitwise_right_shift, _right_shift_docstring -) - - -def dpnp_right_shift(x1, x2, out=None, order="K"): - """Invokes bitwise_right_shift() from dpctl.tensor implementation for right_shift() function.""" - - # dpctl.tensor only works with usm_ndarray or scalar - x1_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x1) - x2_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x2) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = right_shift_func( - x1_usm_or_scalar, x2_usm_or_scalar, out=out_usm, order=order - ) - return _get_result(res_usm, out=out) - - -_round_docstring = """ -round(x, out=None, order='K') - -Rounds each element `x_i` of the input array `x` to -the nearest integer-valued number. - -Args: - x (dpnp.ndarray): - Input array, expected to have numeric data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Return: - dpnp.ndarray: - An array containing the element-wise rounded value. The data type - of the returned array is determined by the Type Promotion Rules. -""" - -round_func = _make_unary_func( - "round", dpt.round, _round_docstring, vmi._mkl_round_to_call, vmi._round -) - - -def dpnp_round(x, out=None, order="K"): - """ - Invokes round() function from pybind11 extension of OneMKL VM if possible. - - Otherwise fully relies on dpctl.tensor implementation for round() function. - """ - # dpctl.tensor only works with usm_ndarray - x1_usm = dpnp.get_usm_ndarray(x) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = round_func(x1_usm, out=out_usm, order=order) - return _get_result(res_usm, out=out) - - -_rsqrt_docstring = """ -rsqrt(x, out=None, order="K") - -Computes the reciprocal square-root for each element `x_i` for input array `x`. - -Args: - x (dpnp.ndarray): - Input array, expected to have a real floating-point data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Returns: - dpnp.ndarray: - An array containing the element-wise reciprocal square-root. - The data type of the returned array is determined by - the Type Promotion Rules. -""" - -rsqrt_func = _make_unary_func("rsqrt", dpt.rsqrt, _rsqrt_docstring) - - -def dpnp_rsqrt(x, out=None, order="K"): - """Invokes rsqrt() from dpctl.tensor implementation for rsqrt() function.""" - - # dpctl.tensor only works with usm_ndarray - x1_usm = dpnp.get_usm_ndarray(x) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = rsqrt_func(x1_usm, out=out_usm, order=order) - return _get_result(res_usm, out=out) - - -_sign_docstring = """ -sign(x, out=None, order="K") - -Computes an indication of the sign of each element `x_i` of input array `x` -using the signum function. - -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`. - -Args: - x (dpnp.ndarray): - Input array, expected to have numeric data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Returns: - dpnp.ndarray: - An array containing the element-wise results. The data type of the - returned array is determined by the Type Promotion Rules. -""" - -sign_func = _make_unary_func("sign", dpt.sign, _sign_docstring) - - -def dpnp_sign(x, out=None, order="K"): - """Invokes sign() from dpctl.tensor implementation for sign() function.""" - - # TODO: discuss with dpctl if the check is needed to be moved there - if not dpnp.isscalar(x) and x.dtype == dpnp.bool: - raise TypeError("DPNP boolean sign is not supported.") - - # dpctl.tensor only works with usm_ndarray - x1_usm = dpnp.get_usm_ndarray(x) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = sign_func(x1_usm, out=out_usm, order=order) - return _get_result(res_usm, out=out) - - -_signbit_docstring = """ -signbit(x, out=None, order="K") - -Computes an indication of whether the sign bit of each element `x_i` of -input array `x` is set. - -Args: - x (dpnp.ndarray): - Input array, expected to have numeric data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Returns: - dpnp.ndarray: - An array containing the element-wise results. The returned array - must have a data type of `bool`. -""" - -signbit_func = _make_unary_func("signbit", dpt.signbit, _signbit_docstring) - - -def dpnp_signbit(x, out=None, order="K"): - """Invokes signbit() from dpctl.tensor implementation for signbit() function.""" - - # dpctl.tensor only works with usm_ndarray - x1_usm = dpnp.get_usm_ndarray(x) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = signbit_func(x1_usm, out=out_usm, order=order) - return _get_result(res_usm, out=out) - - -_sin_docstring = """ -sin(x, out=None, order='K') - -Computes sine for each element `x_i` of input array `x`. - -Args: - x (dpnp.ndarray): - Input array, expected to have numeric data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Return: - dpnp.ndarray: - An array containing the element-wise sine. The data type of the - returned array is determined by the Type Promotion Rules. -""" - -sin_func = _make_unary_func( - "sin", dpt.sin, _sin_docstring, vmi._mkl_sin_to_call, vmi._sin -) - - -def dpnp_sin(x, out=None, order="K"): - """ - Invokes sin() function from pybind11 extension of OneMKL VM if possible. - - Otherwise fully relies on dpctl.tensor implementation for sin() function. - """ - - # dpctl.tensor only works with usm_ndarray - x1_usm = dpnp.get_usm_ndarray(x) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = sin_func(x1_usm, out=out_usm, order=order) - return _get_result(res_usm, out=out) - - -_sinh_docstring = """ -sinh(x, out=None, order='K') - -Computes hyperbolic sine for each element `x_i` for input array `x`. - -Args: - x (dpnp.ndarray): - Input array, expected to have numeric data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Return: - dpnp.ndarray: - An array containing the element-wise hyperbolic sine. The data type - of the returned array is determined by the Type Promotion Rules. -""" - -sinh_func = _make_unary_func( - "sinh", dpt.sinh, _sinh_docstring, vmi._mkl_sinh_to_call, vmi._sinh -) - - -def dpnp_sinh(x, out=None, order="K"): - """ - Invokes sinh() function from pybind11 extension of OneMKL VM if possible. - - Otherwise fully relies on dpctl.tensor implementation for sinh() function. - - """ - # dpctl.tensor only works with usm_ndarray - x1_usm = dpnp.get_usm_ndarray(x) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = sinh_func(x1_usm, out=out_usm, order=order) - return _get_result(res_usm, out=out) - - -_sqrt_docstring = """ -sqrt(x, out=None, order='K') - -Computes the non-negative square-root for each element `x_i` for input array `x`. - -Args: - x (dpnp.ndarray): - Input array. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Return: - dpnp.ndarray: - An array containing the element-wise square-root results. -""" - -sqrt_func = _make_unary_func( - "sqrt", dpt.sqrt, _sqrt_docstring, vmi._mkl_sqrt_to_call, vmi._sqrt -) - - -def dpnp_sqrt(x, out=None, order="K"): - """ - Invokes sqrt() function from pybind11 extension of OneMKL VM if possible. - - Otherwise fully relies on dpctl.tensor implementation for sqrt() function. - """ - - # dpctl.tensor only works with usm_ndarray or scalar - x_usm = dpnp.get_usm_ndarray(x) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = sqrt_func(x_usm, out=out_usm, order=order) - return _get_result(res_usm, out=out) - - -_square_docstring = """ -square(x, out=None, order='K') - -Computes `x_i**2` (or `x_i*x_i`) for each element `x_i` of input array `x`. - -Args: - x (dpnp.ndarray): - Input array. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Return: - dpnp.ndarray: - An array containing the element-wise square results. -""" - -square_func = _make_unary_func( - "square", dpt.square, _square_docstring, vmi._mkl_sqr_to_call, vmi._sqr -) - - -def dpnp_square(x, out=None, order="K"): - """ - Invokes sqr() function from pybind11 extension of OneMKL VM if possible. - - Otherwise fully relies on dpctl.tensor implementation for square() function. - """ - - # dpctl.tensor only works with usm_ndarray or scalar - x_usm = dpnp.get_usm_ndarray(x) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = square_func(x_usm, out=out_usm, order=order) - return _get_result(res_usm, out=out) - - -_subtract_docstring = """ -subtract(x1, x2, out=None, order="K") - -Calculates the difference between each element `x1_i` of the input -array `x1` and the respective element `x2_i` of the input array `x2`. - -Args: - x1 (dpnp.ndarray): - First input array, expected to have numeric data type. - x2 (dpnp.ndarray): - Second input array, also expected to have numeric data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C","F","A","K", None, optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Returns: - dpnp.ndarray: - an array containing the result of element-wise subtraction. The data type - of the returned array is determined by the Type Promotion Rules. -""" - -subtract_func = _make_binary_func( - "subtract", - dpt.subtract, - _subtract_docstring, - vmi._mkl_sub_to_call, - vmi._sub, -) - - -def dpnp_subtract(x1, x2, out=None, order="K"): - """ - Invokes sub() function from pybind11 extension of OneMKL VM if possible. - - Otherwise fully relies on dpctl.tensor implementation for subtract() function. - - """ - - # dpctl.tensor only works with usm_ndarray or scalar - x1_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x1) - x2_usm_or_scalar = dpnp.get_usm_ndarray_or_scalar(x2) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - # TODO: discuss with dpctl if the check is needed to be moved out of there - boolean_subtract = False - if dpnp.isscalar(x1): - if isinstance(x1, bool) and x2.dtype == dpnp.bool: - boolean_subtract = True - elif dpnp.isscalar(x2): - if isinstance(x2, bool) and x1.dtype == dpnp.bool: - boolean_subtract = True - elif x1.dtype == x2.dtype == dpnp.bool: - boolean_subtract = True - - if boolean_subtract: +def acceptance_fn_subtract( + arg1_dtype, arg2_dtype, buf1_dt, buf2_dt, res_dt, sycl_dev +): + # subtract is not defined for boolean data type + if arg1_dtype.char == "?" and arg2_dtype.char == "?": raise TypeError( - "DPNP boolean subtract, the `-` operator, is not supported, " - "use the bitwise_xor, the `^` operator, or the logical_xor function instead." + "The `subtract` function, the `-` operator, is not supported " + "for inputs of data type bool, use the `^` operator, the " + "`bitwise_xor`, or the `logical_xor` function instead" ) - - res_usm = subtract_func( - x1_usm_or_scalar, x2_usm_or_scalar, out=out_usm, order=order - ) - return _get_result(res_usm, out=out) - - -_tan_docstring = """ -tan(x, out=None, order='K') - -Computes tangent for each element `x_i` for input array `x`. - -Args: - x (dpnp.ndarray): - Input array, expected to have numeric data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Return: - dpnp.ndarray: - An array containing the element-wise tangent. The data type - of the returned array is determined by the Type Promotion Rules. -""" - -tan_func = _make_unary_func( - "tan", dpt.tan, _tan_docstring, vmi._mkl_tan_to_call, vmi._tan -) - - -def dpnp_tan(x, out=None, order="K"): - """ - Invokes tan() function from pybind11 extension of OneMKL VM if possible. - - Otherwise fully relies on dpctl.tensor implementation for tan() function. - - """ - # dpctl.tensor only works with usm_ndarray - x1_usm = dpnp.get_usm_ndarray(x) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = tan_func(x1_usm, out=out_usm, order=order) - return _get_result(res_usm, out=out) - - -_tanh_docstring = """ -tanh(x, out=None, order='K') - -Computes hyperbolic tangent for each element `x_i` for input array `x`. - -Args: - x (dpnp.ndarray): - Input array, expected to have numeric data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Return: - dpnp.ndarray: - An array containing the element-wise hyperbolic tangent. The data type - of the returned array is determined by the Type Promotion Rules. -""" - -tanh_func = _make_unary_func( - "tanh", dpt.tanh, _tanh_docstring, vmi._mkl_tanh_to_call, vmi._tanh -) - - -def dpnp_tanh(x, out=None, order="K"): - """ - Invokes tanh() function from pybind11 extension of OneMKL VM if possible. - - Otherwise fully relies on dpctl.tensor implementation for tanh() function. - - """ - # dpctl.tensor only works with usm_ndarray - x1_usm = dpnp.get_usm_ndarray(x) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = tanh_func(x1_usm, out=out_usm, order=order) - return _get_result(res_usm, out=out) - - -_trunc_docstring = """ -trunc(x, out=None, order='K') - -Returns the truncated value for each element `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 -signed number `x` is discarded. - -Args: - x (dpnp.ndarray): - Input array, expected to have a real-valued data type. - out ({None, dpnp.ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order ("C", "F", "A", "K", optional): - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". -Return: - dpnp.ndarray: - An array containing the truncated value of each element in `x`. The data type - of the returned array is determined by the Type Promotion Rules. -""" - -trunc_func = _make_unary_func( - "trunc", dpt.trunc, _trunc_docstring, vmi._mkl_trunc_to_call, vmi._trunc -) - - -def dpnp_trunc(x, out=None, order="K"): - """ - Invokes trunc() function from pybind11 extension of OneMKL VM if possible. - - Otherwise fully relies on dpctl.tensor implementation for trunc() function. - """ - # dpctl.tensor only works with usm_ndarray - x1_usm = dpnp.get_usm_ndarray(x) - out_usm = None if out is None else dpnp.get_usm_ndarray(out) - - res_usm = trunc_func(x1_usm, out=out_usm, order=order) - return _get_result(res_usm, out=out) + else: + return True diff --git a/dpnp/dpnp_iface_bitwise.py b/dpnp/dpnp_iface_bitwise.py index 1d7f3432e87a..91560732d3f9 100644 --- a/dpnp/dpnp_iface_bitwise.py +++ b/dpnp/dpnp_iface_bitwise.py @@ -37,18 +37,13 @@ """ +# pylint: disable=protected-access +# pylint: disable=c-extension-no-member -import numpy -from .dpnp_algo.dpnp_elementwise_common import ( - check_nd_call_func, - dpnp_bitwise_and, - dpnp_bitwise_or, - dpnp_bitwise_xor, - dpnp_invert, - dpnp_left_shift, - dpnp_right_shift, -) +import dpctl.tensor._tensor_elementwise_impl as ti + +from dpnp.dpnp_algo.dpnp_elementwise_common import DPNPBinaryFunc, DPNPUnaryFunc __all__ = [ "bitwise_and", @@ -61,395 +56,380 @@ ] -def bitwise_and( - x1, - x2, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Compute the bit-wise AND of two arrays element-wise. - - For full documentation refer to :obj:`numpy.bitwise_and`. - - Returns - ------- - out : dpnp.ndarray - An array containing the element-wise results. - - Limitations - ----------- - Parameters `x1` and `x2` are supported as either scalar, :class:`dpnp.ndarray` - or :class:`dpctl.tensor.usm_ndarray`, but both `x1` and `x2` can not be scalars at the same time. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Keyword argument `kwargs` is currently unsupported. - Otherwise the function will be executed sequentially on CPU. - Data type of input arrays `x1` and `x2` has to be an integer or boolean data type. - - See Also - -------- - :obj:`dpnp.logical_and` : Compute the truth value of ``x1`` AND ``x2`` element-wise. - :obj:`dpnp.bitwise_or`: Compute the bit-wise OR of two arrays element-wise. - :obj:`dpnp.bitwise_xor` : Compute the bit-wise XOR of two arrays element-wise. - - Examples - -------- - >>> import dpnp as np - >>> x1 = np.array([2, 5, 255]) - >>> x2 = np.array([3,14,16]) - >>> np.bitwise_and(x1, x2) - [2, 4, 16] - - >>> a = np.array([True, True]) - >>> b = np.array([False, True]) - >>> np.bitwise_and(a, b) - array([False, True]) - - The ``&`` operator can be used as a shorthand for ``bitwise_and`` on - :class:`dpnp.ndarray`. - - >>> x1 & x2 - array([ 2, 4, 16]) - """ - return check_nd_call_func( - numpy.bitwise_and, - dpnp_bitwise_and, - x1, - x2, - out=out, - order=order, - where=where, - dtype=dtype, - subok=subok, - **kwargs, - ) - - -def bitwise_or( - x1, - x2, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Compute the bit-wise OR of two arrays element-wise. - - For full documentation refer to :obj:`numpy.bitwise_or`. - - Returns - ------- - out : dpnp.ndarray - An array containing the element-wise results. - - Limitations - ----------- - Parameters `x1` and `x2` are supported as either scalar, :class:`dpnp.ndarray` - or :class:`dpctl.tensor.usm_ndarray`, but both `x1` and `x2` can not be scalars at the same time. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Keyword argument `kwargs` is currently unsupported. - Otherwise the function will be executed sequentially on CPU. - Data type of input arrays `x1` and `x2` has to be an integer or boolean data type. - - See Also - -------- - :obj:`dpnp.logical_or` : Compute the truth value of ``x1`` OR ``x2`` element-wise. - :obj:`dpnp.bitwise_and`: Compute the bit-wise AND of two arrays element-wise. - :obj:`dpnp.bitwise_xor` : Compute the bit-wise XOR of two arrays element-wise. - - Examples - -------- - >>> import dpnp as np - >>> x1 = np.array([2, 5, 255]) - >>> x2 = np.array([4]) - >>> np.bitwise_or(x1, x2) - array([ 6, 5, 255]) - - The ``|`` operator can be used as a shorthand for ``bitwise_or`` on - :class:`dpnp.ndarray`. - - >>> x1 | x2 - array([ 6, 5, 255]) - """ - return check_nd_call_func( - numpy.bitwise_or, - dpnp_bitwise_or, - x1, - x2, - out=out, - order=order, - where=where, - dtype=dtype, - subok=subok, - **kwargs, - ) - - -def bitwise_xor( - x1, - x2, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Compute the bit-wise XOR of two arrays element-wise. - - For full documentation refer to :obj:`numpy.bitwise_xor`. - - Returns - ------- - out : dpnp.ndarray - An array containing the element-wise results. - - Limitations - ----------- - Parameters `x1` and `x2` are supported as either scalar, :class:`dpnp.ndarray` - or :class:`dpctl.tensor.usm_ndarray`, but both `x1` and `x2` can not be scalars at the same time. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Keyword argument `kwargs` is currently unsupported. - Otherwise the function will be executed sequentially on CPU. - Data type of input arrays `x1` and `x2` has to be an integer or boolean data type. - - See Also - -------- - :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. - :obj:`dpnp.bitwise_or` : Compute the bit-wise OR of two arrays element-wise. - - Examples - -------- - >>> import dpnp as np - >>> x1 = np.array([31, 3]) - >>> x2 = np.array([5, 6]) - >>> np.bitwise_xor(x1, x2) - array([26, 5]) - - >>> a = np.array([True, True]) - >>> b = np.array([False, True]) - >>> np.bitwise_xor(a, b) - array([ True, False]) - - The ``^`` operator can be used as a shorthand for ``bitwise_xor`` on - :class:`dpnp.ndarray`. - - >>> a ^ b - array([ True, False]) - """ - return check_nd_call_func( - numpy.bitwise_xor, - dpnp_bitwise_xor, - x1, - x2, - out=out, - order=order, - where=where, - dtype=dtype, - subok=subok, - **kwargs, - ) - - -def invert( - x, /, out=None, *, order="K", dtype=None, where=True, subok=True, **kwargs -): - """ - Compute bit-wise inversion, or bit-wise NOT, element-wise. - - For full documentation refer to :obj:`numpy.invert`. - - Returns - ------- - out : dpnp.ndarray - An array containing the element-wise results. - - Limitations - ----------- - Parameter `x` is supported as either :class:`dpnp.ndarray` - or :class:`dpctl.tensor.usm_ndarray`. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Keyword argument `kwargs` is currently unsupported. - Otherwise the function will be executed sequentially on CPU. - Data type of input array `x` has to be an integer data type. - - See Also - -------- - :obj:`dpnp.bitwise_and`: Compute the bit-wise AND of two arrays element-wise. - :obj:`dpnp.bitwise_or` : Compute the bit-wise OR of two arrays element-wise. - :obj:`dpnp.bitwise_xor` : Compute the bit-wise XOR of two arrays element-wise. - :obj:`dpnp.logical_not` : Compute the truth value of NOT x element-wise. - - Examples - -------- - >>> import dpnp as np - >>> x = np.array([13]) - >>> np.invert(x) - -14 - - >>> a = np.array([True, False]) - >>> np.invert(a) - array([False, True]) - - The ``~`` operator can be used as a shorthand for ``invert`` on - :class:`dpnp.ndarray`. - - >>> ~a - array([False, True]) - """ - - return check_nd_call_func( - numpy.invert, - dpnp_invert, - x, - out=out, - order=order, - where=where, - dtype=dtype, - subok=subok, - **kwargs, - ) +_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`. + +For full documentation refer to :obj:`numpy.bitwise_and`. + +Parameters +---------- +x1 : {dpnp.ndarray, usm_ndarray} + First input array, expected to have integer or boolean data type. +x2 : {dpnp.ndarray, usm_ndarray} + Second input array, also expected to have integer or boolean data + type. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +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. + +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 +-------- +:obj:`dpnp.logical_and` : Compute the truth value of ``x1`` AND ``x2`` element-wise. +:obj:`dpnp.bitwise_or`: Compute the bit-wise OR of two arrays element-wise. +:obj:`dpnp.bitwise_xor` : Compute the bit-wise XOR of two arrays element-wise. + +Examples +-------- +>>> import dpnp as np +>>> x1 = np.array([2, 5, 255]) +>>> x2 = np.array([3,14,16]) +>>> np.bitwise_and(x1, x2) +[2, 4, 16] + +>>> a = np.array([True, True]) +>>> b = np.array([False, True]) +>>> np.bitwise_and(a, b) +array([False, True]) + +The ``&`` operator can be used as a shorthand for ``bitwise_and`` on +:class:`dpnp.ndarray`. + +>>> x1 & x2 +array([ 2, 4, 16]) +""" + +bitwise_and = DPNPBinaryFunc( + "bitwise_and", + ti._bitwise_and_result_type, + ti._bitwise_and, + _BITWISE_AND_DOCSTRING, +) + + +_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`. + +For full documentation refer to :obj:`numpy.bitwise_or`. + +Parameters +---------- +x1 : {dpnp.ndarray, usm_ndarray} + First input array, expected to have integer or boolean data type. +x2 : {dpnp.ndarray, usm_ndarray} + Second input array, also expected to have integer or boolean data + type. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +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. + +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 +-------- +:obj:`dpnp.logical_or` : Compute the truth value of ``x1`` OR ``x2`` element-wise. +:obj:`dpnp.bitwise_and`: Compute the bit-wise AND of two arrays element-wise. +:obj:`dpnp.bitwise_xor` : Compute the bit-wise XOR of two arrays element-wise. + +Examples +-------- +>>> import dpnp as np +>>> x1 = np.array([2, 5, 255]) +>>> x2 = np.array([4]) +>>> np.bitwise_or(x1, x2) +array([ 6, 5, 255]) + +The ``|`` operator can be used as a shorthand for ``bitwise_or`` on +:class:`dpnp.ndarray`. + +>>> x1 | x2 +array([ 6, 5, 255]) +""" + +bitwise_or = DPNPBinaryFunc( + "bitwise_or", + ti._bitwise_or_result_type, + ti._bitwise_or, + _BITWISE_OR_DOCSTRING, +) + + +_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`. + +For full documentation refer to :obj:`numpy.bitwise_xor`. + +Parameters +---------- +x1 : {dpnp.ndarray, usm_ndarray} + First input array, expected to have integer or boolean data type. +x2 : {dpnp.ndarray, usm_ndarray} + Second input array, also expected to have integer or boolean data + type. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +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. + +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 +-------- +: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. +:obj:`dpnp.bitwise_or` : Compute the bit-wise OR of two arrays element-wise. + +Examples +-------- +>>> import dpnp as np +>>> x1 = np.array([31, 3]) +>>> x2 = np.array([5, 6]) +>>> np.bitwise_xor(x1, x2) +array([26, 5]) + +>>> a = np.array([True, True]) +>>> b = np.array([False, True]) +>>> np.bitwise_xor(a, b) +array([ True, False]) + +The ``^`` operator can be used as a shorthand for ``bitwise_xor`` on +:class:`dpnp.ndarray`. + +>>> a ^ b +array([ True, False]) +""" + +bitwise_xor = DPNPBinaryFunc( + "bitwise_xor", + ti._bitwise_xor_result_type, + ti._bitwise_xor, + _BITWISE_XOR_DOCSTRING, +) + + +_INVERT_DOCSTRING = """ +Inverts (flips) each bit for each element `x_i` of the input array `x`. + +For full documentation refer to :obj:`numpy.invert`. + +Parameters +---------- +x : {dpnp.ndarray, usm_ndarray} + Input array, expected to have integer or boolean data type. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +Returns +------- +out : dpnp.ndarray + An array containing the element-wise results. + The data type of the returned array is same as the data type of the + input array. + +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 +-------- +:obj:`dpnp.bitwise_and`: Compute the bit-wise AND of two arrays element-wise. +:obj:`dpnp.bitwise_or` : Compute the bit-wise OR of two arrays element-wise. +:obj:`dpnp.bitwise_xor` : Compute the bit-wise XOR of two arrays element-wise. +:obj:`dpnp.logical_not` : Compute the truth value of NOT x element-wise. + +Examples +-------- +>>> import dpnp as np +>>> x = np.array([13]) +>>> np.invert(x) +-14 + +>>> a = np.array([True, False]) +>>> np.invert(a) +array([False, True]) + +The ``~`` operator can be used as a shorthand for ``invert`` on +:class:`dpnp.ndarray`. + +>>> ~a +array([False, True]) +""" + +invert = DPNPUnaryFunc( + "invert", + ti._bitwise_invert_result_type, + ti._bitwise_invert, + _INVERT_DOCSTRING, +) bitwise_not = invert # bitwise_not is an alias for invert -def left_shift( - x1, - x2, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Shift the bits of an integer to the left. - - For full documentation refer to :obj:`numpy.left_shift`. - - Returns - ------- - out : dpnp.ndarray - An array containing the element-wise results. - - Limitations - ----------- - Parameters `x1` and `x2` are supported as either scalar, :class:`dpnp.ndarray` - or :class:`dpctl.tensor.usm_ndarray`, but both `x1` and `x2` can not be scalars at the same time. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Keyword argument `kwargs` is currently unsupported. - Otherwise the function will be executed sequentially on CPU. - Input data is supported as integer only. - - See Also - -------- - :obj:`dpnp.right_shift` : Shift the bits of an integer to the right. - - Examples - -------- - >>> import dpnp as np - >>> x1 = np.array([5]) - >>> x2 = np.array([1, 2, 3]) - >>> np.left_shift(x1, x2) - array([10, 20, 40]) - - The ``<<`` operator can be used as a shorthand for ``left_shift`` on - :class:`dpnp.ndarray`. - - >>> x1 << x2 - array([10, 20, 40]) - """ - return check_nd_call_func( - numpy.left_shift, - dpnp_left_shift, - x1, - x2, - out=out, - order=order, - where=where, - dtype=dtype, - subok=subok, - **kwargs, - ) - - -def right_shift( - x1, - x2, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Shift the bits of an integer to the right. - - For full documentation refer to :obj:`numpy.right_shift`. - - Returns - ------- - out : dpnp.ndarray - An array containing the element-wise results. - - Limitations - ----------- - Parameters `x1` and `x2` are supported as either scalar, :class:`dpnp.ndarray` - or :class:`dpctl.tensor.usm_ndarray`, but both `x1` and `x2` can not be scalars at the same time. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Keyword argument `kwargs` is currently unsupported. - Otherwise the function will be executed sequentially on CPU. - Input data is supported as integer only. - - See Also - -------- - :obj:`dpnp.left_shift` : Shift the bits of an integer to the left. - - Examples - -------- - >>> import dpnp as np - >>> x1 = np.array([10]) - >>> x2 = np.array([1, 2, 3]) - >>> np.right_shift(x1, x2) - array([5, 2, 1]) - - The ``>>`` operator can be used as a shorthand for ``right_shift`` on - :class:`dpnp.ndarray`. - - >>> x1 >> x2 - array([5, 2, 1]) - """ - return check_nd_call_func( - numpy.right_shift, - dpnp_right_shift, - x1, - x2, - out=out, - order=order, - where=where, - dtype=dtype, - subok=subok, - **kwargs, - ) +_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`. + +For full documentation refer to :obj:`numpy.left_shift`. + +Parameters +---------- +x1 : {dpnp.ndarray, usm_ndarray} + First input array, expected to have integer data type. +x2 : {dpnp.ndarray, usm_ndarray} + Second input array, also expected to have integer data type. + Each element must be greater than or equal to 0. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". +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. + +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 +-------- +:obj:`dpnp.right_shift` : Shift the bits of an integer to the right. + +Examples +-------- +>>> import dpnp as np +>>> x1 = np.array([5]) +>>> x2 = np.array([1, 2, 3]) +>>> np.left_shift(x1, x2) +array([10, 20, 40]) + +The ``<<`` operator can be used as a shorthand for ``left_shift`` on +:class:`dpnp.ndarray`. + +>>> x1 << x2 +array([10, 20, 40]) +""" + +left_shift = DPNPBinaryFunc( + "left_shift", + ti._bitwise_left_shift_result_type, + ti._bitwise_left_shift, + _LEFT_SHIFT_DOCSTRING, +) + + +_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`. + +For full documentation refer to :obj:`numpy.right_shift`. + +Parameters +---------- +x1 : {dpnp.ndarray, usm_ndarray} + First input array, expected to have integer data type. +x2 : {dpnp.ndarray, usm_ndarray} + Second input array, also expected to have integer data type. + Each element must be greater than or equal to 0. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +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. + +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 +-------- +:obj:`dpnp.left_shift` : Shift the bits of an integer to the left. + +Examples +-------- +>>> import dpnp as np +>>> x1 = np.array([10]) +>>> x2 = np.array([1, 2, 3]) +>>> np.right_shift(x1, x2) +array([5, 2, 1]) + +The ``>>`` operator can be used as a shorthand for ``right_shift`` on +:class:`dpnp.ndarray`. + +>>> x1 >> x2 +array([5, 2, 1]) +""" + +right_shift = DPNPBinaryFunc( + "right_shift", + ti._bitwise_right_shift_result_type, + ti._bitwise_right_shift, + _RIGHT_SHIFT_DOCSTRING, +) diff --git a/dpnp/dpnp_iface_logic.py b/dpnp/dpnp_iface_logic.py index 4e711f6c5dc6..edceee0e144b 100644 --- a/dpnp/dpnp_iface_logic.py +++ b/dpnp/dpnp_iface_logic.py @@ -39,31 +39,21 @@ """ +# pylint: disable=protected-access +# pylint: disable=c-extension-no-member +# pylint: disable=duplicate-code +# pylint: disable=no-name-in-module + import dpctl.tensor as dpt +import dpctl.tensor._tensor_elementwise_impl as ti import numpy import dpnp -from dpnp.dpnp_algo import * +from dpnp.dpnp_algo import dpnp_allclose +from dpnp.dpnp_algo.dpnp_elementwise_common import DPNPBinaryFunc, DPNPUnaryFunc from dpnp.dpnp_array import dpnp_array -from dpnp.dpnp_utils import * - -from .dpnp_algo.dpnp_elementwise_common import ( - check_nd_call_func, - dpnp_equal, - dpnp_greater, - dpnp_greater_equal, - dpnp_isfinite, - dpnp_isinf, - dpnp_isnan, - dpnp_less, - dpnp_less_equal, - dpnp_logical_and, - dpnp_logical_not, - dpnp_logical_or, - dpnp_logical_xor, - dpnp_not_equal, -) +from dpnp.dpnp_utils import call_origin __all__ = [ "all", @@ -109,7 +99,8 @@ def all(x, /, axis=None, out=None, keepdims=False, *, where=True): See Also -------- :obj:`dpnp.ndarray.all` : equivalent method - :obj:`dpnp.any` : Test whether any element along a given axis evaluates to True. + :obj:`dpnp.any` : Test whether any element along a given axis evaluates + to True. Notes ----- @@ -216,15 +207,11 @@ def allclose(a, b, rtol=1.0e-5, atol=1.0e-8, **kwargs): else: if not dpnp.isscalar(rtol): raise TypeError( - "An argument `rtol` must be a scalar, but got {}".format( - type(rtol) - ) + f"An argument `rtol` must be a scalar, but got {rtol}" ) - elif not dpnp.isscalar(atol): + if not dpnp.isscalar(atol): raise TypeError( - "An argument `atol` must be a scalar, but got {}".format( - type(atol) - ) + f"An argument `atol` must be a scalar, but got {atol}" ) if dpnp.isscalar(a): @@ -265,7 +252,8 @@ def any(x, /, axis=None, out=None, keepdims=False, *, where=True): See Also -------- :obj:`dpnp.ndarray.any` : equivalent method - :obj:`dpnp.all` : Test whether all elements along a given axis evaluate to True. + :obj:`dpnp.all` : Test whether all elements along a given axis evaluate + to True. Notes ----- @@ -308,225 +296,205 @@ def any(x, /, axis=None, out=None, keepdims=False, *, where=True): ) -def equal( - x1, - x2, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Return the truth value of (x1 == x2) element-wise. - - For full documentation refer to :obj:`numpy.equal`. - - Returns - ------- - out : dpnp.ndarray - Output array of bool type, element-wise comparison of `x1` and `x2`. - - Limitations - ----------- - Parameters `x1` and `x2` are supported as either scalar, :class:`dpnp.ndarray` - or :class:`dpctl.tensor.usm_ndarray`, but both `x1` and `x2` can not be scalars at the same time. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. - - See Also - -------- - :obj:`dpnp.not_equal` : Return (x1 != x2) element-wise. - :obj:`dpnp.greater_equal` : Return the truth value of (x1 >= x2) element-wise. - :obj:`dpnp.less_equal` : Return the truth value of (x1 =< x2) element-wise. - :obj:`dpnp.greater` : Return the truth value of (x1 > x2) element-wise. - :obj:`dpnp.less` : Return the truth value of (x1 < x2) element-wise. - - Examples - -------- - >>> import dpnp as np - >>> x1 = np.array([0, 1, 3]) - >>> x2 = np.arange(3) - >>> np.equal(x1, x2) - array([ True, True, False]) - - What is compared are values, not types. So an int (1) and an array of - length one can evaluate as True: - - >>> np.equal(1, np.ones(1)) - array([ True]) - - The ``==`` operator can be used as a shorthand for ``equal`` on - :class:`dpnp.ndarray`. - - >>> a = np.array([2, 4, 6]) - >>> b = np.array([2, 4, 2]) - >>> a == b - array([ True, True, False]) - - """ - - return check_nd_call_func( - numpy.equal, - dpnp_equal, - x1, - x2, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) - - -def greater( - x1, - x2, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Return the truth value of (x1 > x2) element-wise. - - For full documentation refer to :obj:`numpy.greater`. - - Returns - ------- - out : dpnp.ndarray - Output array of bool type, element-wise comparison of `x1` and `x2`. - - Limitations - ----------- - Parameters `x1` and `x2` are supported as either scalar, :class:`dpnp.ndarray` - or :class:`dpctl.tensor.usm_ndarray`, but both `x1` and `x2` can not be scalars at the same time. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. - - See Also - -------- - :obj:`dpnp.greater_equal` : Return the truth value of (x1 >= x2) element-wise. - :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. - :obj:`dpnp.equal` : Return (x1 == x2) element-wise. - :obj:`dpnp.not_equal` : Return (x1 != x2) element-wise. - - Examples - -------- - >>> import dpnp as np - >>> x1 = np.array([4, 2]) - >>> x2 = np.array([2, 2]) - >>> np.greater(x1, x2) - array([ True, False]) - - The ``>`` operator can be used as a shorthand for ``greater`` on - :class:`dpnp.ndarray`. - - >>> a = np.array([4, 2]) - >>> b = np.array([2, 2]) - >>> a > b - array([ True, False]) - - """ - - return check_nd_call_func( - numpy.greater, - dpnp_greater, - x1, - x2, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) - - -def greater_equal( - x1, - x2, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Return the truth value of (x1 >= x2) element-wise. - - For full documentation refer to :obj:`numpy.greater_equal`. - - Returns - ------- - out : dpnp.ndarray - Output array of bool type, element-wise comparison of `x1` and `x2`. +_EQUAL_DOCSTRING = """ +Calculates equality results for each element `x1_i` of +the input array `x1` the respective element `x2_i` of the input array `x2`. + +For full documentation refer to :obj:`numpy.equal`. + +Parameters +---------- +x1 : {dpnp.ndarray, usm_ndarray} + First input array, expected to have numeric data type. +x2 : {dpnp.ndarray, usm_ndarray} + Second input array, also expected to have numeric data type. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +Returns +------- +out : dpnp.ndarray + an array containing the result of element-wise equality comparison. + The data type of the returned array is determined by the Type Promotion Rules. + +Limitations +----------- +Parameters `where` and `subok` are supported with their default values. +Otherwise ``NotImplementedError`` exception will be raised. + +See Also +-------- +:obj:`dpnp.not_equal` : Return (x1 != x2) element-wise. +:obj:`dpnp.greater_equal` : Return the truth value of (x1 >= x2) element-wise. +:obj:`dpnp.less_equal` : Return the truth value of (x1 =< x2) element-wise. +:obj:`dpnp.greater` : Return the truth value of (x1 > x2) element-wise. +:obj:`dpnp.less` : Return the truth value of (x1 < x2) element-wise. + +Examples +-------- +>>> import dpnp as np +>>> x1 = np.array([0, 1, 3]) +>>> x2 = np.arange(3) +>>> np.equal(x1, x2) +array([ True, True, False]) + +What is compared are values, not types. So an int (1) and an array of +length one can evaluate as True: + +>>> np.equal(1, np.ones(1)) +array([ True]) + +The ``==`` operator can be used as a shorthand for ``equal`` on +:class:`dpnp.ndarray`. + +>>> a = np.array([2, 4, 6]) +>>> b = np.array([2, 4, 2]) +>>> a == b +array([ True, True, False]) +""" - Limitations - ----------- - Parameters `x1` and `x2` are supported as either scalar, :class:`dpnp.ndarray` - or :class:`dpctl.tensor.usm_ndarray`, but both `x1` and `x2` can not be scalars at the same time. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. +equal = DPNPBinaryFunc( + "equal", + ti._equal_result_type, + ti._equal, + _EQUAL_DOCSTRING, +) - See Also - -------- - :obj:`dpnp.greater` : Return the truth value of (x1 > x2) element-wise. - :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. - :obj:`dpnp.equal` : Return (x1 == x2) element-wise. - :obj:`dpnp.not_equal` : Return (x1 != x2) element-wise. - Examples - -------- - >>> import dpnp as np - >>> x1 = np.array([4, 2, 1]) - >>> x2 = np.array([2, 2, 2]) - >>> np.greater_equal(x1, x2) - array([ True, True, False]) +_GREATER_DOCSTRING = """ +Calculates the greater-than results for each element `x1_i` of +the input array `x1` the respective element `x2_i` of the input array `x2`. + +For full documentation refer to :obj:`numpy.greater`. + +Parameters +---------- +x1 : {dpnp.ndarray, usm_ndarray} + First input array, expected to have numeric data type. +x2 : {dpnp.ndarray, usm_ndarray} + Second input array, also expected to have numeric data type. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +Returns +------- +out : dpnp.ndarray + an array containing the result of element-wise greater-than comparison. + The data type of the returned array is determined by the Type Promotion Rules. + +Limitations +----------- +Parameters `where` and `subok` are supported with their default values. +Otherwise ``NotImplementedError`` exception will be raised. + +See Also +-------- +:obj:`dpnp.greater_equal` : Return the truth value of (x1 >= x2) element-wise. +: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. +:obj:`dpnp.equal` : Return (x1 == x2) element-wise. +:obj:`dpnp.not_equal` : Return (x1 != x2) element-wise. + +Examples +-------- +>>> import dpnp as np +>>> x1 = np.array([4, 2]) +>>> x2 = np.array([2, 2]) +>>> np.greater(x1, x2) +array([ True, False]) + +The ``>`` operator can be used as a shorthand for ``greater`` on +:class:`dpnp.ndarray`. + +>>> a = np.array([4, 2]) +>>> b = np.array([2, 2]) +>>> a > b +array([ True, False]) +""" - The ``>=`` operator can be used as a shorthand for ``greater_equal`` on - :class:`dpnp.ndarray`. +greater = DPNPBinaryFunc( + "greater", + ti._greater_result_type, + ti._greater, + _GREATER_DOCSTRING, +) - >>> a = np.array([4, 2, 1]) - >>> b = np.array([2, 2, 2]) - >>> a >= b - array([ True, True, False]) - """ +_GREATER_EQUAL_DOCSTRING = """ +Calculates the greater-than or equal-to results for each element `x1_i` of +the input array `x1` the respective element `x2_i` of the input array `x2`. + +For full documentation refer to :obj:`numpy.greater_equal`. + +Parameters +---------- +x1 : {dpnp.ndarray, usm_ndarray} + First input array, expected to have numeric data type. +x2 : {dpnp.ndarray, usm_ndarray} + Second input array, also expected to have numeric data type. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +Returns +------- +out : dpnp.ndarray + an array containing the result of element-wise greater-than or equal-to comparison. + The data type of the returned array is determined by the Type Promotion Rules. + +Limitations +----------- +Parameters `where` and `subok` are supported with their default values. +Otherwise ``NotImplementedError`` exception will be raised. + +See Also +-------- +:obj:`dpnp.greater` : Return the truth value of (x1 > x2) element-wise. +: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. +:obj:`dpnp.equal` : Return (x1 == x2) element-wise. +:obj:`dpnp.not_equal` : Return (x1 != x2) element-wise. + +Examples +-------- +>>> import dpnp as np +>>> x1 = np.array([4, 2, 1]) +>>> x2 = np.array([2, 2, 2]) +>>> np.greater_equal(x1, x2) +array([ True, True, False]) + +The ``>=`` operator can be used as a shorthand for ``greater_equal`` on +:class:`dpnp.ndarray`. + +>>> a = np.array([4, 2, 1]) +>>> b = np.array([2, 2, 2]) +>>> a >= b +array([ True, True, False]) +""" - return check_nd_call_func( - numpy.greater_equal, - dpnp_greater_equal, - x1, - x2, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) +greater_equal = DPNPBinaryFunc( + "greater", + ti._greater_equal_result_type, + ti._greater_equal, + _GREATER_EQUAL_DOCSTRING, +) def isclose(x1, x2, rtol=1e-05, atol=1e-08, equal_nan=False): """ - Returns a boolean array where two arrays are element-wise equal within a tolerance. + Returns a boolean array where two arrays are element-wise equal within + a tolerance. For full documentation refer to :obj:`numpy.isclose`. @@ -539,7 +507,8 @@ def isclose(x1, x2, rtol=1e-05, atol=1e-08, equal_nan=False): See Also -------- - :obj:`dpnp.allclose` : Returns True if two arrays are element-wise equal within a tolerance. + :obj:`dpnp.allclose` : Returns True if two arrays are element-wise equal + within a tolerance. Examples -------- @@ -555,7 +524,9 @@ def isclose(x1, x2, rtol=1e-05, atol=1e-08, equal_nan=False): # x1_desc = dpnp.get_dpnp_descriptor(x1) # x2_desc = dpnp.get_dpnp_descriptor(x2) # if x1_desc and x2_desc: - # result_obj = dpnp_isclose(x1_desc, x2_desc, rtol, atol, equal_nan).get_pyobj() + # result_obj = dpnp_isclose( + # x1_desc, x2_desc, rtol, atol, equal_nan + # ).get_pyobj() # return result_obj return call_origin( @@ -563,639 +534,598 @@ def isclose(x1, x2, rtol=1e-05, atol=1e-08, equal_nan=False): ) -def isfinite( - x, /, out=None, *, where=True, order="K", dtype=None, subok=True, **kwargs -): - """ - Test element-wise for finiteness (not infinity or not Not a Number). - - For full documentation refer to :obj:`numpy.isfinite`. - - Limitations - ----------- - Parameters `x` is only supported as either :class:`dpnp.ndarray` or :class:`dpctl.tensor.usm_ndarray`. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. - - See Also - -------- - :obj:`dpnp.isinf` : Test element-wise for positive or negative infinity. - :obj:`dpnp.isneginf` : Test element-wise for negative infinity, - return result as bool array. - :obj:`dpnp.isposinf` : Test element-wise for positive infinity, - return result as bool array. - :obj:`dpnp.isnan` : Test element-wise for NaN and - return result as a boolean array. - - Notes - ----- - Not a Number, positive infinity and negative infinity are considered - to be non-finite. - - Examples - -------- - >>> import dpnp as np - >>> x = np.array([-np.inf, 0., np.inf]) - >>> np.isfinite(x) - array([False, True, False]) - - """ - - return check_nd_call_func( - numpy.isfinite, - dpnp_isfinite, - x, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) - - -def isinf( - x, /, out=None, *, where=True, order="K", dtype=None, subok=True, **kwargs -): - """ - Test element-wise for positive or negative infinity. - - For full documentation refer to :obj:`numpy.isinf`. - - Limitations - ----------- - Parameters `x` is only supported as either :class:`dpnp.ndarray` or :class:`dpctl.tensor.usm_ndarray`. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. - - See Also - -------- - :obj:`dpnp.isneginf` : Test element-wise for negative infinity, - return result as bool array. - :obj:`dpnp.isposinf` : Test element-wise for positive infinity, - return result as bool array. - :obj:`dpnp.isnan` : Test element-wise for NaN and - return result as a boolean array. - :obj:`dpnp.isfinite` : Test element-wise for finiteness. - - Examples - -------- - >>> import dpnp as np - >>> x = np.array([-np.inf, 0., np.inf]) - >>> np.isinf(x) - array([ True, False, True]) - - """ - - return check_nd_call_func( - numpy.isinf, - dpnp_isinf, - x, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) - - -def isnan( - x, /, out=None, *, where=True, order="K", dtype=None, subok=True, **kwargs -): - """ - Test element-wise for NaN and return result as a boolean array. - - For full documentation refer to :obj:`numpy.isnan`. - - Limitations - ----------- - Parameters `x` is only supported as either :class:`dpnp.ndarray` or :class:`dpctl.tensor.usm_ndarray`. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. - - See Also - -------- - :obj:`dpnp.isinf` : Test element-wise for positive or negative infinity. - :obj:`dpnp.isneginf` : Test element-wise for negative infinity, - return result as bool array. - :obj:`dpnp.isposinf` : Test element-wise for positive infinity, - return result as bool array. - :obj:`dpnp.isfinite` : Test element-wise for finiteness. - :obj:`dpnp.isnat` : Test element-wise for NaT (not a time) - and return result as a boolean array. - - Examples - -------- - >>> import dpnp as np - >>> x = np.array([np.inf, 0., np.nan]) - >>> np.isnan(x) - array([False, False, True]) - - """ - - return check_nd_call_func( - numpy.isnan, - dpnp_isnan, - x, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) - - -def less( - x1, - x2, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Return the truth value of (x1 < x2) element-wise. - - For full documentation refer to :obj:`numpy.less`. - - Returns - ------- - out : dpnp.ndarray - Output array of bool type, element-wise comparison of `x1` and `x2`. - - Limitations - ----------- - Parameters `x1` and `x2` are supported as either scalar, :class:`dpnp.ndarray` - or :class:`dpctl.tensor.usm_ndarray`, but both `x1` and `x2` can not be scalars at the same time. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. - - See Also - -------- - :obj:`dpnp.greater` : Return the truth value of (x1 > x2) element-wise. - :obj:`dpnp.less_equal` : Return the truth value of (x1 =< x2) element-wise. - :obj:`dpnp.greater_equal` : Return the truth value of (x1 >= x2) element-wise. - :obj:`dpnp.equal` : Return (x1 == x2) element-wise. - :obj:`dpnp.not_equal` : Return (x1 != x2) element-wise. - - Examples - -------- - >>> import dpnp as np - >>> x1 = np.array([1, 2]) - >>> x2 = np.array([2, 2]) - >>> np.less(x1, x2) - array([ True, False]) - - The ``<`` operator can be used as a shorthand for ``less`` on - :class:`dpnp.ndarray`. - - >>> a = np.array([1, 2]) - >>> b = np.array([2, 2]) - >>> a < b - array([ True, False]) - - """ - - return check_nd_call_func( - numpy.less, - dpnp_less, - x1, - x2, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) - - -def less_equal( - x1, - x2, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Return the truth value of (x1 <= x2) element-wise. - - For full documentation refer to :obj:`numpy.less_equal`. - - Returns - ------- - out : dpnp.ndarray - Output array of bool type, element-wise comparison of `x1` and `x2`. - - Limitations - ----------- - Parameters `x1` and `x2` are supported as either scalar, :class:`dpnp.ndarray` - or :class:`dpctl.tensor.usm_ndarray`, but both `x1` and `x2` can not be scalars at the same time. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. - - See Also - -------- - :obj:`dpnp.greater` : Return the truth value of (x1 > x2) element-wise. - :obj:`dpnp.less` : Return the truth value of (x1 < x2) element-wise. - :obj:`dpnp.greater_equal` : Return the truth value of (x1 >= x2) element-wise. - :obj:`dpnp.equal` : Return (x1 == x2) element-wise. - :obj:`dpnp.not_equal` : Return (x1 != x2) element-wise. - - Examples - -------- - >>> import dpnp as np - >>> x1 = np.array([4, 2, 1]) - >>> x2 = np.array([2, 2, 2] - >>> np.less_equal(x1, x2) - array([False, True, True]) - - The ``<=`` operator can be used as a shorthand for ``less_equal`` on - :class:`dpnp.ndarray`. - - >>> a = np.array([4, 2, 1]) - >>> b = np.array([2, 2, 2]) - >>> a <= b - array([False, True, True]) - - """ - - return check_nd_call_func( - numpy.less_equal, - dpnp_less_equal, - x1, - x2, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) - - -def logical_and( - x1, - x2, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Compute the truth value of x1 AND x2 element-wise. - - For full documentation refer to :obj:`numpy.logical_and`. - - Returns - ------- - out : dpnp.ndarray - Boolean result of the logical AND operation applied to the elements - of `x1` and `x2`; the shape is determined by broadcasting. - - Limitations - ----------- - Parameters `x1` and `x2` are supported as either scalar, :class:`dpnp.ndarray` - or :class:`dpctl.tensor.usm_ndarray`, but both `x1` and `x2` can not be scalars at the same time. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. - - See Also - -------- - :obj:`dpnp.logical_or` : Compute the truth value of x1 OR x2 element-wise. - :obj:`dpnp.logical_not` : Compute the truth value of NOT x element-wise. - :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. - - Examples - -------- - >>> import dpnp as np - >>> x1 = np.array([True, False]) - >>> x2 = np.array([False, False]) - >>> np.logical_and(x1, x2) - array([False, False]) - - >>> x = np.arange(5) - >>> np.logical_and(x > 1, x < 4) - array([False, False, True, True, False]) - - The ``&`` operator can be used as a shorthand for ``logical_and`` on - boolean :class:`dpnp.ndarray`. - - >>> a = np.array([True, False]) - >>> b = np.array([False, False]) - >>> a & b - array([False, False]) - - """ - - return check_nd_call_func( - numpy.logical_and, - dpnp_logical_and, - x1, - x2, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) - - -def logical_not( - x, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Compute the truth value of NOT x element-wise. - - For full documentation refer to :obj:`numpy.logical_not`. - - Returns - ------- - out : dpnp.ndarray - Boolean result with the same shape as `x` of the NOT operation - on elements of `x`. - - Limitations - ----------- - Parameters `x` is only supported as either :class:`dpnp.ndarray` or :class:`dpctl.tensor.usm_ndarray`. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. - - See Also - -------- - :obj:`dpnp.logical_and` : Compute the truth value of x1 AND x2 element-wise. - :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. - - Examples - -------- - >>> import dpnp as np - >>> x = np.array([True, False, 0, 1]) - >>> np.logical_not(x) - array([False, True, True, False]) - - >>> x = np.arange(5) - >>> np.logical_not(x < 3) - array([False, False, False, True, True]) - - """ - - return check_nd_call_func( - numpy.logical_not, - dpnp_logical_not, - x, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) - +_ISFINITE_DOCSTRING = """ +Checks if each element of input array is a finite number. + +For full documentation refer to :obj:`numpy.isfinite`. + +Parameters +---------- +x : {dpnp.ndarray, usm_ndarray} + Input array, expected to have numeric data type. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +Returns +------- +out : dpnp.ndarray + An array which is True where `x` is not positive infinity, + negative infinity, or NaN, False otherwise. + The data type of the returned array is `bool`. + +Limitations +----------- +Parameters `where` and `subok` are supported with their default values. +Otherwise ``NotImplementedError`` exception will be raised. + +See Also +-------- +:obj:`dpnp.isinf` : Test element-wise for positive or negative infinity. +:obj:`dpnp.isneginf` : Test element-wise for negative infinity, + return result as bool array. +:obj:`dpnp.isposinf` : Test element-wise for positive infinity, + return result as bool array. +:obj:`dpnp.isnan` : Test element-wise for NaN and + return result as a boolean array. -def logical_or( - x1, - x2, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Compute the truth value of x1 OR x2 element-wise. - - For full documentation refer to :obj:`numpy.logical_or`. - - Returns - ------- - out : dpnp.ndarray - Boolean result of the logical OR operation applied to the elements - of `x1` and `x2`; the shape is determined by broadcasting. - - Limitations - ----------- - Parameters `x1` and `x2` are supported as either scalar, :class:`dpnp.ndarray` - or :class:`dpctl.tensor.usm_ndarray`, but both `x1` and `x2` can not be scalars at the same time. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. - - See Also - -------- - :obj:`dpnp.logical_and` : Compute the truth value of x1 AND x2 element-wise. - :obj:`dpnp.logical_not` : Compute the truth value of NOT x element-wise. - :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. - - Examples - -------- - >>> import dpnp as np - >>> x1 = np.array([True, False]) - >>> x2 = np.array([False, False]) - >>> np.logical_or(x1, x2) - array([ True, False]) +Notes +----- +Not a Number, positive infinity and negative infinity are considered +to be non-finite. + +Examples +-------- +>>> import dpnp as np +>>> x = np.array([-np.inf, 0., np.inf]) +>>> np.isfinite(x) +array([False, True, False]) +""" - >>> x = np.arange(5) - >>> np.logical_or(x < 1, x > 3) - array([ True, False, False, False, True]) +isfinite = DPNPUnaryFunc( + "isfinite", + ti._isfinite_result_type, + ti._isfinite, + _ISFINITE_DOCSTRING, +) - The ``|`` operator can be used as a shorthand for ``logical_or`` on - boolean :class:`dpnp.ndarray`. - >>> a = np.array([True, False]) - >>> b = np.array([False, False]) - >>> a | b - array([ True, False]) +_ISINF_DOCSTRING = """ +Checks if each element of input array is an infinity. + +For full documentation refer to :obj:`numpy.isinf`. + +Parameters +---------- +x : {dpnp.ndarray, usm_ndarray} + Input array, expected to have numeric data type. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +Returns +------- +out : dpnp.ndarray + An array which is True where `x` is positive or negative infinity, + False otherwise. The data type of the returned array is `bool`. + +Limitations +----------- +Parameters `where` and `subok` are supported with their default values. +Otherwise ``NotImplementedError`` exception will be raised. + +See Also +-------- +:obj:`dpnp.isneginf` : Test element-wise for negative infinity, + return result as bool array. +:obj:`dpnp.isposinf` : Test element-wise for positive infinity, + return result as bool array. +:obj:`dpnp.isnan` : Test element-wise for NaN and + return result as a boolean array. +:obj:`dpnp.isfinite` : Test element-wise for finiteness. + +Examples +-------- +>>> import dpnp as np +>>> x = np.array([-np.inf, 0., np.inf]) +>>> np.isinf(x) +array([ True, False, True]) +""" - """ +isinf = DPNPUnaryFunc( + "isinf", + ti._isinf_result_type, + ti._isinf, + _ISINF_DOCSTRING, +) - return check_nd_call_func( - numpy.logical_or, - dpnp_logical_or, - x1, - x2, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) +_ISNAN_DOCSTRING = """ +Checks if each element of an input array is a NaN. + +For full documentation refer to :obj:`numpy.isnan`. + +Parameters +---------- +x : {dpnp.ndarray, usm_ndarray} + Input array, expected to have numeric data type. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +Returns +------- +out : dpnp.ndarray + An array which is True where x is NaN, False otherwise. + The data type of the returned array is `bool`. + +Limitations +----------- +Parameters `where` and `subok` are supported with their default values. +Otherwise ``NotImplementedError`` exception will be raised. + +See Also +-------- +:obj:`dpnp.isinf` : Test element-wise for positive or negative infinity. +:obj:`dpnp.isneginf` : Test element-wise for negative infinity, + return result as bool array. +:obj:`dpnp.isposinf` : Test element-wise for positive infinity, + return result as bool array. +:obj:`dpnp.isfinite` : Test element-wise for finiteness. +:obj:`dpnp.isnat` : Test element-wise for NaT (not a time) + and return result as a boolean array. + +Examples +-------- +>>> import dpnp as np +>>> x = np.array([np.inf, 0., np.nan]) +>>> np.isnan(x) +array([False, False, True]) +""" -def logical_xor( - x1, - x2, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Compute the truth value of x1 XOR x2 element-wise. +isnan = DPNPUnaryFunc( + "isnan", + ti._isnan_result_type, + ti._isnan, + _ISNAN_DOCSTRING, +) - For full documentation refer to :obj:`numpy.logical_xor`. - Returns - ------- - out : dpnp.ndarray - Boolean result of the logical XOR operation applied to the elements - of `x1` and `x2`; the shape is determined by broadcasting. +_LESS_DOCSTRING = """ +Calculates the less-than results for each element `x1_i` of +the input array `x1` the respective element `x2_i` of the input array `x2`. + +For full documentation refer to :obj:`numpy.less`. + +Parameters +---------- +x1 : {dpnp.ndarray, usm_ndarray} + First input array, expected to have numeric data type. +x2 : {dpnp.ndarray, usm_ndarray} + Second input array, also expected to have numeric data type. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +Returns +------- +out : dpnp.ndarray + An array containing the result of element-wise less-than comparison. + The data type of the returned array is determined by the Type Promotion Rules. + +Limitations +----------- +Parameters `where` and `subok` are supported with their default values. +Otherwise ``NotImplementedError`` exception will be raised. +See Also +-------- +:obj:`dpnp.greater` : Return the truth value of (x1 > x2) element-wise. +:obj:`dpnp.less_equal` : Return the truth value of (x1 =< x2) element-wise. +:obj:`dpnp.greater_equal` : Return the truth value of (x1 >= x2) element-wise. +:obj:`dpnp.equal` : Return (x1 == x2) element-wise. +:obj:`dpnp.not_equal` : Return (x1 != x2) element-wise. + +Examples +-------- +>>> import dpnp as np +>>> x1 = np.array([1, 2]) +>>> x2 = np.array([2, 2]) +>>> np.less(x1, x2) +array([ True, False]) + +The ``<`` operator can be used as a shorthand for ``less`` on +:class:`dpnp.ndarray`. + +>>> a = np.array([1, 2]) +>>> b = np.array([2, 2]) +>>> a < b +array([ True, False]) +""" - Limitations - ----------- - Parameters `x1` and `x2` are supported as either scalar, :class:`dpnp.ndarray` - or :class:`dpctl.tensor.usm_ndarray`, but both `x1` and `x2` can not be scalars at the same time. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. +less = DPNPBinaryFunc( + "less", + ti._less_result_type, + ti._less, + _LESS_DOCSTRING, +) - See Also - -------- - :obj:`dpnp.logical_and` : Compute the truth value of x1 AND x2 element-wise. - :obj:`dpnp.logical_or` : Compute the truth value of x1 OR x2 element-wise. - :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. - Examples - -------- - >>> import dpnp as np - >>> x1 = np.array([True, True, False, False]) - >>> x2 = np.array([True, False, True, False]) - >>> np.logical_xor(x1, x2) - array([False, True, True, False]) +_LESS_EQUAL_DOCSTRING = """ +Calculates the less-than or equal-to results for each element `x1_i` of +the input array `x1` the respective element `x2_i` of the input array `x2`. + +For full documentation refer to :obj:`numpy.less_equal`. + +Parameters +---------- +x1 : {dpnp.ndarray, usm_ndarray} + First input array, expected to have numeric data type. +x2 : {dpnp.ndarray, usm_ndarray} + Second input array, also expected to have numeric data type. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +Returns +------- +out : dpnp.ndarray + An array containing the result of element-wise less-than or equal-to comparison. + The data type of the returned array is determined by the Type Promotion Rules. + +Limitations +----------- +Parameters `where` and `subok` are supported with their default values. +Otherwise ``NotImplementedError`` exception will be raised. + +See Also +-------- +:obj:`dpnp.greater` : Return the truth value of (x1 > x2) element-wise. +:obj:`dpnp.less` : Return the truth value of (x1 < x2) element-wise. +:obj:`dpnp.greater_equal` : Return the truth value of (x1 >= x2) element-wise. +:obj:`dpnp.equal` : Return (x1 == x2) element-wise. +:obj:`dpnp.not_equal` : Return (x1 != x2) element-wise. + +Examples +-------- +>>> import dpnp as np +>>> x1 = np.array([4, 2, 1]) +>>> x2 = np.array([2, 2, 2] +>>> np.less_equal(x1, x2) +array([False, True, True]) + +The ``<=`` operator can be used as a shorthand for ``less_equal`` on +:class:`dpnp.ndarray`. + +>>> a = np.array([4, 2, 1]) +>>> b = np.array([2, 2, 2]) +>>> a <= b +array([False, True, True]) +""" - >>> x = np.arange(5) - >>> np.logical_xor(x < 1, x > 3) - array([ True, False, False, False, True]) +less_equal = DPNPBinaryFunc( + "less_equal", + ti._less_equal_result_type, + ti._less_equal, + _LESS_EQUAL_DOCSTRING, +) - Simple example showing support of broadcasting - >>> np.logical_xor(0, np.eye(2)) - array([[ True, False], - [False, True]]) +_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`. + +For full documentation refer to :obj:`numpy.logical_and`. + +Parameters +---------- +x1 : {dpnp.ndarray, usm_ndarray} + First input array. +x2 : {dpnp.ndarray, usm_ndarray} + Second input array. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +Returns +------- +out : dpnp.ndarray + An array containing the element-wise logical AND results. + +Limitations +----------- +Parameters `where` and `subok` are supported with their default values. +Otherwise ``NotImplementedError`` exception will be raised. + +See Also +-------- +:obj:`dpnp.logical_or` : Compute the truth value of x1 OR x2 element-wise. +:obj:`dpnp.logical_not` : Compute the truth value of NOT x element-wise. +: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. + +Examples +-------- +>>> import dpnp as np +>>> x1 = np.array([True, False]) +>>> x2 = np.array([False, False]) +>>> np.logical_and(x1, x2) +array([False, False]) + +>>> x = np.arange(5) +>>> np.logical_and(x > 1, x < 4) +array([False, False, True, True, False]) + +The ``&`` operator can be used as a shorthand for ``logical_and`` on +boolean :class:`dpnp.ndarray`. + +>>> a = np.array([True, False]) +>>> b = np.array([False, False]) +>>> a & b +array([False, False]) +""" - """ +logical_and = DPNPBinaryFunc( + "logical_and", + ti._logical_and_result_type, + ti._logical_and, + _LOGICAL_AND_DOCSTRING, +) - return check_nd_call_func( - numpy.logical_xor, - dpnp_logical_xor, - x1, - x2, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) +_LOGICAL_NOT_DOCSTRING = """ +Computes the logical NOT for each element `x_i` of input array `x`. + +For full documentation refer to :obj:`numpy.logical_not`. + +Parameters +---------- +x : {dpnp.ndarray, usm_ndarray} + Input array. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +Returns +------- +out : dpnp.ndarray + An array containing the element-wise logical NOT results. + +Limitations +----------- +Parameters `where` and `subok` are supported with their default values. +Otherwise ``NotImplementedError`` exception will be raised. + +See Also +-------- +:obj:`dpnp.logical_and` : Compute the truth value of x1 AND x2 element-wise. +: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. + +Examples +-------- +>>> import dpnp as np +>>> x = np.array([True, False, 0, 1]) +>>> np.logical_not(x) +array([False, True, True, False]) + +>>> x = np.arange(5) +>>> np.logical_not(x < 3) +array([False, False, False, True, True]) +""" -def not_equal( - x1, - x2, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Return the truth value of (x1 != x2) element-wise. +logical_not = DPNPUnaryFunc( + "logical_not", + ti._logical_not_result_type, + ti._logical_not, + _LOGICAL_NOT_DOCSTRING, +) - For full documentation refer to :obj:`numpy.not_equal`. - Returns - ------- - out : dpnp.ndarray - Output array of bool type, element-wise comparison of `x1` and `x2`. +_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`. + +For full documentation refer to :obj:`numpy.logical_or`. + +Parameters +---------- +x1 : {dpnp.ndarray, usm_ndarray} + First input array. +x2 : {dpnp.ndarray, usm_ndarray} + Second input array. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +Returns +------- +out : dpnp.ndarray + An array containing the element-wise logical OR results. + +Limitations +----------- +Parameters `where` and `subok` are supported with their default values. +Otherwise ``NotImplementedError`` exception will be raised. + +See Also +-------- +:obj:`dpnp.logical_and` : Compute the truth value of x1 AND x2 element-wise. +:obj:`dpnp.logical_not` : Compute the truth value of NOT x element-wise. +: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. + +Examples +-------- +>>> import dpnp as np +>>> x1 = np.array([True, False]) +>>> x2 = np.array([False, False]) +>>> np.logical_or(x1, x2) +array([ True, False]) + +>>> x = np.arange(5) +>>> np.logical_or(x < 1, x > 3) +array([ True, False, False, False, True]) + +The ``|`` operator can be used as a shorthand for ``logical_or`` on +boolean :class:`dpnp.ndarray`. + +>>> a = np.array([True, False]) +>>> b = np.array([False, False]) +>>> a | b +array([ True, False]) +""" - Limitations - ----------- - Parameters `x1` and `x2` are supported as either scalar, :class:`dpnp.ndarray` - or :class:`dpctl.tensor.usm_ndarray`, but both `x1` and `x2` can not be scalars at the same time. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. +logical_or = DPNPBinaryFunc( + "logical_or", + ti._logical_or_result_type, + ti._logical_or, + _LOGICAL_OR_DOCSTRING, +) - See Also - -------- - :obj:`dpnp.equal` : Return (x1 == x2) element-wise. - :obj:`dpnp.greater` : Return the truth value of (x1 > x2) element-wise. - :obj:`dpnp.greater_equal` : Return the truth value of (x1 >= x2) element-wise. - :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. - Examples - -------- - >>> import dpnp as np - >>> x1 = np.array([1., 2.]) - >>> x2 = np.arange(1., 3.) - >>> np.not_equal(x1, x2) - array([False, False]) +_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`. + +For full documentation refer to :obj:`numpy.logical_xor`. + +Parameters +---------- +x1 : {dpnp.ndarray, usm_ndarray} + First input array. +x2 : {dpnp.ndarray, usm_ndarray} + Second input array. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". +Returns: +dpnp.ndarray: + An array containing the element-wise logical XOR results. + +Limitations +----------- +Parameters `where` and `subok` are supported with their default values. +Otherwise ``NotImplementedError`` exception will be raised. + +See Also +-------- +:obj:`dpnp.logical_and` : Compute the truth value of x1 AND x2 element-wise. +:obj:`dpnp.logical_or` : Compute the truth value of x1 OR x2 element-wise. +: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. + +Examples +-------- +>>> import dpnp as np +>>> x1 = np.array([True, True, False, False]) +>>> x2 = np.array([True, False, True, False]) +>>> np.logical_xor(x1, x2) +array([False, True, True, False]) + +>>> x = np.arange(5) +>>> np.logical_xor(x < 1, x > 3) +array([ True, False, False, False, True]) + +Simple example showing support of broadcasting + +>>> np.logical_xor(0, np.eye(2)) +array([[ True, False], + [False, True]]) +""" - The ``!=`` operator can be used as a shorthand for ``not_equal`` on - :class:`dpnp.ndarray`. +logical_xor = DPNPBinaryFunc( + "logical_xor", + ti._logical_xor_result_type, + ti._logical_xor, + _LOGICAL_XOR_DOCSTRING, +) - >>> a = np.array([1., 2.]) - >>> b = np.array([1., 3.]) - >>> a != b - array([False, True]) - """ +_NOT_EQUAL_DOCSTRING = """ +Calculates inequality results for each element `x1_i` of +the input array `x1` the respective element `x2_i` of the input array `x2`. + +For full documentation refer to :obj:`numpy.not_equal`. + +Parameters +---------- +x1 : {dpnp.ndarray, usm_ndarray} + First input array, expected to have numeric data type. +x2 : {dpnp.ndarray, usm_ndarray} + Second input array, also expected to have numeric data type. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +Returns +------- +out : dpnp.ndarray + an array containing the result of element-wise inequality comparison. + The data type of the returned array is determined by the Type Promotion Rules. + +Limitations +----------- +Parameters `where` and `subok` are supported with their default values. +Otherwise ``NotImplementedError`` exception will be raised. + +See Also +-------- +:obj:`dpnp.equal` : Return (x1 == x2) element-wise. +:obj:`dpnp.greater` : Return the truth value of (x1 > x2) element-wise. +:obj:`dpnp.greater_equal` : Return the truth value of (x1 >= x2) element-wise. +: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. + +Examples +-------- +>>> import dpnp as np +>>> x1 = np.array([1., 2.]) +>>> x2 = np.arange(1., 3.) +>>> np.not_equal(x1, x2) +array([False, False]) + +The ``!=`` operator can be used as a shorthand for ``not_equal`` on +:class:`dpnp.ndarray`. + +>>> a = np.array([1., 2.]) +>>> b = np.array([1., 3.]) +>>> a != b +array([False, True]) +""" - return check_nd_call_func( - numpy.not_equal, - dpnp_not_equal, - x1, - x2, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) +not_equal = DPNPBinaryFunc( + "not_equal", + ti._not_equal_result_type, + ti._not_equal, + _NOT_EQUAL_DOCSTRING, +) diff --git a/dpnp/dpnp_iface_mathematical.py b/dpnp/dpnp_iface_mathematical.py index ed8096be6781..1c8790e238ab 100644 --- a/dpnp/dpnp_iface_mathematical.py +++ b/dpnp/dpnp_iface_mathematical.py @@ -37,48 +37,50 @@ """ +# pylint: disable=protected-access +# pylint: disable=c-extension-no-member +# pylint: disable=duplicate-code +# pylint: disable=no-name-in-module + import dpctl.tensor as dpt +import dpctl.tensor._tensor_elementwise_impl as ti import dpctl.tensor._type_utils as dtu import numpy +from dpctl.tensor._type_utils import _acceptance_fn_divide from numpy.core.numeric import ( normalize_axis_index, normalize_axis_tuple, ) import dpnp +import dpnp.backend.extensions.vm._vm_impl as vmi +from dpnp.backend.extensions.sycl_ext import _sycl_ext_impl from dpnp.dpnp_array import dpnp_array -from dpnp.dpnp_utils import get_usm_allocations - -from .dpnp_algo import * +from dpnp.dpnp_utils import call_origin, get_usm_allocations + +from .dpnp_algo import ( + dpnp_cumprod, + dpnp_ediff1d, + dpnp_fabs, + dpnp_fmax, + dpnp_fmin, + dpnp_fmod, + dpnp_gradient, + dpnp_modf, + dpnp_trapz, +) from .dpnp_algo.dpnp_elementwise_common import ( - check_nd_call_func, - dpnp_abs, - dpnp_add, - dpnp_angle, - dpnp_ceil, - dpnp_conj, - dpnp_copysign, - dpnp_divide, - dpnp_floor, - dpnp_floor_divide, - dpnp_imag, - dpnp_maximum, - dpnp_minimum, - dpnp_multiply, - dpnp_negative, - dpnp_positive, - dpnp_power, - dpnp_proj, - dpnp_real, - dpnp_remainder, - dpnp_round, - dpnp_sign, - dpnp_signbit, - dpnp_subtract, - dpnp_trunc, + DPNPAngle, + DPNPBinaryFunc, + DPNPReal, + DPNPRound, + DPNPUnaryFunc, + acceptance_fn_negative, + acceptance_fn_positive, + acceptance_fn_sign, + acceptance_fn_subtract, ) -from .dpnp_utils import * from .dpnp_utils.dpnp_utils_linearalgebra import dpnp_cross __all__ = [ @@ -156,213 +158,219 @@ def _append_to_diff_array(a, axis, combined, values): combined.append(values) -def absolute( - x, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Calculate the absolute value element-wise. - - For full documentation refer to :obj:`numpy.absolute`. - - Returns - ------- - out : dpnp.ndarray - An array containing the absolute value of each element in `x`. - - Limitations - ----------- - Parameters `x` is only supported as either :class:`dpnp.ndarray` or :class:`dpctl.tensor.usm_ndarray`. - Parameters `out`, `where`, `dtype` and `subok` are supported with their default values. - Keyword argument `kwargs` is currently unsupported. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. +_ABS_DOCSTRING = """ +Calculate the absolute value element-wise. + +For full documentation refer to :obj:`numpy.absolute`. + +Parameters +---------- +x : {dpnp.ndarray, usm_ndarray} + Input array, expected to have numeric data type. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +Returns +------- +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 + 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`. + +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 +-------- +:obj:`dpnp.fabs` : Calculate the absolute value element-wise excluding complex types. - See Also - -------- - :obj:`dpnp.fabs` : Calculate the absolute value element-wise excluding complex types. +Notes +----- +``dpnp.abs`` is a shorthand for this function. + +Examples +-------- +>>> import dpnp as np +>>> a = np.array([-1.2, 1.2]) +>>> np.absolute(a) +array([1.2, 1.2]) + +>>> a = np.array(1.2 + 1j) +>>> np.absolute(a) +array(1.5620499351813308) +""" - Notes - ----- - ``dpnp.abs`` is a shorthand for this function. +absolute = DPNPUnaryFunc( + "abs", + ti._abs_result_type, + ti._abs, + _ABS_DOCSTRING, + mkl_fn_to_call=vmi._mkl_abs_to_call, + mkl_impl_fn=vmi._abs, +) - Examples - -------- - >>> import dpnp as np - >>> a = np.array([-1.2, 1.2]) - >>> np.absolute(a) - array([1.2, 1.2]) - >>> a = np.array(1.2 + 1j) - >>> np.absolute(a) - array(1.5620499351813308) +abs = absolute - """ - return check_nd_call_func( - numpy.absolute, - dpnp_abs, - x, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) +_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`. + +For full documentation refer to :obj:`numpy.add`. + +Parameters +---------- +x1 : {dpnp.ndarray, usm_ndarray} + First input array, expected to have numeric data type. +x2 : {dpnp.ndarray, usm_ndarray} + Second input array, also expected to have numeric data type. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +Returns +------- +out : dpnp.ndarray + an array containing the result of element-wise addition. The data type + of the returned array is determined by the Type Promotion Rules. + +Limitations +----------- +Parameters `where` and `subok` are supported with their default values. +Keyword argument `kwargs` is currently unsupported. +Otherwise ``NotImplementedError`` exception will be raised. +Notes +----- +Equivalent to `x1` + `x2` in terms of array broadcasting. + +Examples +-------- +>>> import dpnp as np +>>> a = np.array([1, 2, 3]) +>>> b = np.array([1, 2, 3]) +>>> np.add(a, b) +array([2, 4, 6]) + +>>> x1 = np.arange(9.0).reshape((3, 3)) +>>> x2 = np.arange(3.0) +>>> np.add(x1, x2) +array([[ 0., 2., 4.], + [ 3., 5., 7.], + [ 6., 8., 10.]]) + +The ``+`` operator can be used as a shorthand for ``add`` on +:class:`dpnp.ndarray`. + +>>> x1 + x2 +array([[ 0., 2., 4.], + [ 3., 5., 7.], + [ 6., 8., 10.]]) +""" -abs = absolute +add = DPNPBinaryFunc( + "add", + ti._add_result_type, + ti._add, + _ADD_DOCSTRING, + mkl_fn_to_call=vmi._mkl_add_to_call, + mkl_impl_fn=vmi._add, + binary_inplace_fn=ti._add_inplace, +) -def add( - x1, - x2, - /, - out=None, - *, - where=True, - order="K", - dtype=None, - subok=True, - **kwargs, -): - """ - Add arguments element-wise. - For full documentation refer to :obj:`numpy.add`. +_ANGLE_DOCSTRING = """ +Computes the phase angle (also called the argument) of each element `x_i` for +input array `x`. - Returns - ------- - out : dpnp.ndarray - The sum of `x1` and `x2`, element-wise. +For full documentation refer to :obj:`numpy.angle`. - Limitations - ----------- - Parameters `x1` and `x2` are supported as either scalar, :class:`dpnp.ndarray` - or :class:`dpctl.tensor.usm_ndarray`, but both `x1` and `x2` can not be scalars at the same time. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Keyword argument `kwargs` is currently unsupported. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. +Parameters +---------- +x : {dpnp.ndarray, usm_ndarray} + Input array, expected to have a complex-valued floating-point data type. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". - Notes - ----- - Equivalent to `x1` + `x2` in terms of array broadcasting. +Returns +------- +out : dpnp.ndarray + An array containing the element-wise phase angles. + The returned array has a floating-point data type determined + by the Type Promotion Rules. - Examples - -------- - >>> import dpnp as np - >>> a = np.array([1, 2, 3]) - >>> b = np.array([1, 2, 3]) - >>> np.add(a, b) - array([2, 4, 6]) - - >>> x1 = np.arange(9.0).reshape((3, 3)) - >>> x2 = np.arange(3.0) - >>> np.add(x1, x2) - array([[ 0., 2., 4.], - [ 3., 5., 7.], - [ 6., 8., 10.]]) - - The ``+`` operator can be used as a shorthand for ``add`` on - :class:`dpnp.ndarray`. - - >>> x1 + x2 - array([[ 0., 2., 4.], - [ 3., 5., 7.], - [ 6., 8., 10.]]) - """ +Notes +----- +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. + +Examples +-------- +>>> import dpnp as np +>>> a = np.array([1.0, 1.0j, 1+1j]) +>>> np.angle(a) # in radians +array([0. , 1.57079633, 0.78539816]) # may vary + +>>> np.angle(a, deg=True) # in degrees +array([ 0., 90., 45.]) +""" - return check_nd_call_func( - numpy.add, - dpnp_add, - x1, - x2, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) +angle = DPNPAngle( + "angle", + ti._angle_result_type, + ti._angle, + _ANGLE_DOCSTRING, +) -def angle(z, deg=False): +def around(x, /, decimals=0, out=None): """ - Return the angle of the complex argument. + Round an array to the given number of decimals. - For full documentation refer to :obj:`numpy.angle`. + For full documentation refer to :obj:`numpy.around`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have a complex-valued floating-point data type. - deg : bool, optional - Return angle in degrees if True, radians if False (default). - - Returns - ------- - out : dpnp.ndarray - The counterclockwise angle from the positive real axis on - the complex plane in the range `(-pi, pi]`. - The returned array has a floating-point data type determined - by the Type Promotion Rules. - - Notes - ----- - 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. - - Examples - -------- - >>> import dpnp as np - >>> a = np.array([1.0, 1.0j, 1+1j]) - >>> np.angle(a) # in radians - array([0. , 1.57079633, 0.78539816]) # may vary - - >>> np.angle(a, deg=True) # in degrees - array([ 0., 90., 45.]) - - """ - - dpnp.check_supported_arrays_type(z) - res = dpnp_angle(z) - if deg is True: - res = res * (180 / dpnp.pi) - return res - - -def around(x, /, decimals=0, out=None): - """ - Round an array to the given number of decimals. + Input array, expected to have 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. + out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. - For full documentation refer to :obj:`numpy.around`. Returns ------- out : dpnp.ndarray The rounded value of elements of the array. - Limitations - ----------- - Parameter `x` is only supported as either :class:`dpnp.ndarray` or :class:`dpctl.tensor.usm_ndarray`. - Parameters `decimals` is supported with its default value. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. - See Also -------- :obj:`dpnp.round` : Equivalent function; see for details. @@ -380,60 +388,56 @@ def around(x, /, decimals=0, out=None): return round(x, decimals, out) -def ceil( - x, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Compute the ceiling of the input, element-wise. - - For full documentation refer to :obj:`numpy.ceil`. - - Returns - ------- - out : dpnp.ndarray - The ceiling of each element of `x`. - - Limitations - ----------- - Parameter `x` is only supported as either :class:`dpnp.ndarray` or :class:`dpctl.tensor.usm_ndarray`. - Parameters `where`, `dtype`, and `subok` are supported with their default values. - Keyword argument `kwargs` is currently unsupported. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by real-value data types. - - See Also - -------- - :obj:`dpnp.floor` : Return the floor of the input, element-wise. - :obj:`dpnp.trunc` : Return the truncated value of the input, element-wise. - - Examples - -------- - >>> import dpnp as np - >>> 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_DOCSTRING = """ +Returns the ceiling for each element `x_i` for input array `x`. +The ceil of the scalar `x` is the smallest integer `i`, such that `i >= x`. + +For full documentation refer to :obj:`numpy.ceil`. + +Parameters +---------- +x : {dpnp.ndarray, usm_ndarray} + Input array, expected to have a real-valued data type. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +Returns +------- +out : dpnp.ndarray + An array containing the element-wise ceiling of input array. + The returned array has the same data type as `x`. + +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 +-------- +:obj:`dpnp.floor` : Return the floor of the input, element-wise. +:obj:`dpnp.trunc` : Return the truncated value of the input, element-wise. + +Examples +-------- +>>> import dpnp as np +>>> 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]) +""" - return check_nd_call_func( - numpy.ceil, - dpnp_ceil, - x, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) +ceil = DPNPUnaryFunc( + "ceil", + ti._ceil_result_type, + ti._ceil, + _CEIL_DOCSTRING, + mkl_fn_to_call=vmi._mkl_ceil_to_call, + mkl_impl_fn=vmi._ceil, +) def clip(a, a_min, a_max, *, out=None, order="K", **kwargs): @@ -447,11 +451,13 @@ def clip(a, a_min, a_max, *, out=None, order="K", **kwargs): a : {dpnp.ndarray, usm_ndarray} Array containing elements to clip. a_min, a_max : {dpnp.ndarray, usm_ndarray, None} - Minimum and maximum value. If ``None``, clipping is not performed on the corresponding edge. - Only one of `a_min` and `a_max` may be ``None``. Both are broadcast against `a`. + Minimum and maximum value. If ``None``, clipping is not performed on + the corresponding edge. Only one of `a_min` and `a_max` may be + ``None``. Both are broadcast against `a`. out : {None, dpnp.ndarray, usm_ndarray}, optional - The results will be placed in this array. It may be the input array for in-place clipping. - `out` must be of the right shape to hold the output. Its type is preserved. + The results will be placed in this array. It may be the input array + for in-place clipping. `out` must be of the right shape to hold the + output. Its type is preserved. order : {"C", "F", "A", "K", None}, optional Memory layout of the newly output array, if parameter `out` is `None`. If `order` is ``None``, the default value "K" will be used. @@ -459,8 +465,8 @@ def clip(a, a_min, a_max, *, out=None, order="K", **kwargs): Returns ------- out : dpnp.ndarray - An array with the elements of `a`, but where values < `a_min` are replaced with `a_min`, - and those > `a_max` with `a_max`. + An array with the elements of `a`, but where values < `a_min` are + replaced with `a_min`, and those > `a_max` with `a_max`. Limitations ----------- @@ -493,7 +499,7 @@ def clip(a, a_min, a_max, *, out=None, order="K", **kwargs): if kwargs: raise NotImplementedError(f"kwargs={kwargs} is currently not supported") - elif a_min is None and a_max is None: + if a_min is None and a_max is None: raise ValueError("One of max or min must be given") if order is None: @@ -510,62 +516,53 @@ def clip(a, a_min, a_max, *, out=None, order="K", **kwargs): return dpnp_array._create_from_usm_ndarray(usm_res) -def conjugate( - x, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Return the complex conjugate, element-wise. - - The complex conjugate of a complex number is obtained by changing the - sign of its imaginary part. - - For full documentation refer to :obj:`numpy.conjugate`. - - Returns - ------- - out : dpnp.ndarray - The conjugate of each element of `x`. - - Limitations - ----------- - Parameters `x` is only supported as either :class:`dpnp.ndarray` or :class:`dpctl.tensor.usm_ndarray`. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. - - Examples - -------- - >>> import dpnp as np - >>> np.conjugate(np.array(1+2j)) - (1-2j) - - >>> x = np.eye(2) + 1j * np.eye(2) - >>> np.conjugate(x) - array([[ 1.-1.j, 0.-0.j], - [ 0.-0.j, 1.-1.j]]) - - """ - - return check_nd_call_func( - numpy.conjugate, - dpnp_conj, - x, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) +_CONJ_DOCSTRING = """ +Computes conjugate for each element `x_i` for 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. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +Returns +------- +out : dpnp.ndarray + An array containing the element-wise conjugate. + The returned array has the same data type as `x`. + +Limitations +----------- +Parameters `where` and `subok` are supported with their default values. +Otherwise ``NotImplementedError`` exception will be raised. + +Examples +-------- +>>> import dpnp as np +>>> np.conjugate(np.array(1+2j)) +(1-2j) + +>>> x = np.eye(2) + 1j * np.eye(2) +>>> np.conjugate(x) +array([[ 1.-1.j, 0.-0.j], + [ 0.-0.j, 1.-1.j]]) +""" +conjugate = DPNPUnaryFunc( + "conj", + ti._conj_result_type, + ti._conj, + _CONJ_DOCSTRING, + mkl_fn_to_call=vmi._mkl_conj_to_call, + mkl_impl_fn=vmi._conj, +) conj = conjugate @@ -587,86 +584,66 @@ def convolve(a, v, mode="full"): return call_origin(numpy.convolve, a=a, v=v, mode=mode) -def copysign( - x1, - x2, - /, - out=None, - *, - where=True, - order="K", - dtype=None, - subok=True, - **kwargs, -): - """ - Change the sign of `x1` to that of `x2`, element-wise. - - For full documentation refer to :obj:`numpy.copysign`. - - Parameters - ---------- - x1 : {dpnp.ndarray, usm_ndarray} - First input array, expected to have a real floating-point data type. - x2 : {dpnp.ndarray, usm_ndarray} - Second input array, also 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. - order : {"C", "F", "A", "K"}, optional - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". - - Returns - ------- - out : dpnp.ndarray - The values of `x1` with the sign of `x2`. - - Limitations - ----------- - Parameters `x1` and `x2` are supported as either scalar, :class:`dpnp.ndarray` - or :class:`dpctl.tensor.usm_ndarray`, but both `x1` and `x2` can not be scalars at the same time. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Keyword argument `kwargs` is currently unsupported. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported real-valued data types. - - See Also - -------- - :obj:`dpnp.negative` : Return the numerical negative of each element of `x`. - :obj:`dpnp.positive` : Return the numerical positive of each element of `x`. - - Examples - -------- - >>> import dpnp as np - >>> np.copysign(np.array(1.3), np.array(-1)) - array(-1.3) - >>> 1 / np.copysign(np.array(0), 1) - array(inf) - >>> 1 / np.copysign(np.array(0), -1) - array(-inf) - - >>> x = np.array([-1, 0, 1]) - >>> np.copysign(x, -1.1) - array([-1., -0., -1.]) - >>> np.copysign(x, np.arange(3) - 1) - array([-1., 0., 1.]) - - """ +_COPYSING_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`. + +For full documentation refer to :obj:`numpy.copysign`. + +Parameters +---------- +x1 : {dpnp.ndarray, usm_ndarray} + First input array, expected to have a real floating-point data type. +x2 : {dpnp.ndarray, usm_ndarray} + Second input array, also 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. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +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. + +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 +-------- +:obj:`dpnp.negative` : Return the numerical negative of each element of `x`. +:obj:`dpnp.positive` : Return the numerical positive of each element of `x`. + +Examples +-------- +>>> import dpnp as np +>>> np.copysign(np.array(1.3), np.array(-1)) +array(-1.3) +>>> 1 / np.copysign(np.array(0), 1) +array(inf) +>>> 1 / np.copysign(np.array(0), -1) +array(-inf) + +>>> x = np.array([-1, 0, 1]) +>>> np.copysign(x, -1.1) +array([-1., -0., -1.]) +>>> np.copysign(x, np.arange(3) - 1) +array([-1., 0., 1.]) +""" - return check_nd_call_func( - numpy.copysign, - dpnp_copysign, - x1, - x2, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) +copysign = DPNPBinaryFunc( + "copysign", + ti._copysign_result_type, + ti._copysign, + _COPYSING_DOCSTRING, +) def cross(a, b, axisa=-1, axisb=-1, axisc=-1, axis=None): @@ -817,8 +794,8 @@ def cross(a, b, axisa=-1, axisb=-1, axisc=-1, axis=None): cp = dpnp_cross(a, b, cp, exec_q) if a_shape[-1] == 2 and b_shape[-1] == 2: return cp - else: - return dpnp.moveaxis(cp, -1, axisc) + + return dpnp.moveaxis(cp, -1, axisc) def cumprod(x1, **kwargs): @@ -986,8 +963,10 @@ def diff(a, n=1, axis=-1, prepend=None, append=None): See Also -------- :obj:`dpnp.gradient` : Return the gradient of an N-dimensional array. - :obj:`dpnp.ediff1d` : Compute the differences between consecutive elements of an array. - :obj:`dpnp.cumsum` : Return the cumulative sum of the elements along a given axis. + :obj:`dpnp.ediff1d` : Compute the differences between consecutive elements + of an array. + :obj:`dpnp.cumsum` : Return the cumulative sum of the elements along + a given axis. Examples -------- @@ -1042,80 +1021,78 @@ def diff(a, n=1, axis=-1, prepend=None, append=None): return a -def divide( - x1, - x2, - /, - out=None, - *, - where=True, - order="K", - dtype=None, - subok=True, - **kwargs, -): - """ - Divide arguments element-wise. - - For full documentation refer to :obj:`numpy.divide`. - - Returns - ------- - out : dpnp.ndarray - The quotient `x1/x2`, element-wise. - - Limitations - ----------- - Parameters `x1` and `x2` are supported as either scalar, :class:`dpnp.ndarray` - or :class:`dpctl.tensor.usm_ndarray`, but both `x1` and `x2` can not be scalars at the same time. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Keyword argument `kwargs` is currently unsupported. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. - - Notes - ----- - Equivalent to `x1` / `x2` in terms of array-broadcasting. - - The ``true_divide(x1, x2)`` function is an alias for - ``divide(x1, x2)``. +_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`. + +For full documentation refer to :obj:`numpy.divide`. + +Parameters +---------- +x1 : {dpnp.ndarray, usm_ndarray} + First input array, expected to have numeric data type. +x2 : {dpnp.ndarray, usm_ndarray} + Second input array, also expected to have numeric data type. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +Returns +------- +out : dpnp.ndarray + An array containing the result of element-wise division. The data type + of the returned array is determined by the Type Promotion Rules. + +Limitations +----------- +Parameters `where` and `subok` are supported with their default values. +Keyword argument `kwargs` is currently unsupported. +Otherwise ``NotImplementedError`` exception will be raised. - Examples - -------- - >>> import dpnp as np - >>> np.divide(dp.array([1, -2, 6, -9]), np.array([-2, -2, -2, -2])) - array([-0.5, 1. , -3. , 4.5]) - - >>> x1 = np.arange(9.0).reshape((3, 3)) - >>> x2 = np.arange(3.0) - >>> np.divide(x1, x2) - array([[nan, 1. , 1. ], - [inf, 4. , 2.5], - [inf, 7. , 4. ]]) - - The ``/`` operator can be used as a shorthand for ``divide`` on - :class:`dpnp.ndarray`. - - >>> x1 = np.arange(9.0).reshape((3, 3)) - >>> x2 = 2 * np.ones(3) - >>> x1/x2 - array([[0. , 0.5, 1. ], - [1.5, 2. , 2.5], - [3. , 3.5, 4. ]]) - """ +Notes +----- +Equivalent to `x1` / `x2` in terms of array-broadcasting. + +The ``true_divide(x1, x2)`` function is an alias for +``divide(x1, x2)``. + +Examples +-------- +>>> import dpnp as np +>>> np.divide(dp.array([1, -2, 6, -9]), np.array([-2, -2, -2, -2])) +array([-0.5, 1. , -3. , 4.5]) + +>>> x1 = np.arange(9.0).reshape((3, 3)) +>>> x2 = np.arange(3.0) +>>> np.divide(x1, x2) +array([[nan, 1. , 1. ], + [inf, 4. , 2.5], + [inf, 7. , 4. ]]) + +The ``/`` operator can be used as a shorthand for ``divide`` on +:class:`dpnp.ndarray`. + +>>> x1 = np.arange(9.0).reshape((3, 3)) +>>> x2 = 2 * np.ones(3) +>>> x1/x2 +array([[0. , 0.5, 1. ], + [1.5, 2. , 2.5], + [3. , 3.5, 4. ]]) +""" - return check_nd_call_func( - numpy.divide, - dpnp_divide, - x1, - x2, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) +divide = DPNPBinaryFunc( + "divide", + ti._divide_result_type, + ti._divide, + _DIVIDE_DOCSTRING, + mkl_fn_to_call=vmi._mkl_div_to_call, + mkl_impl_fn=vmi._div, + binary_inplace_fn=ti._divide_inplace, + acceptance_fn=_acceptance_fn_divide, +) def ediff1d(x1, to_end=None, to_begin=None): @@ -1127,13 +1104,15 @@ def ediff1d(x1, to_end=None, to_begin=None): Limitations ----------- Parameter `x1`is supported as :class:`dpnp.ndarray`. - Keyword arguments `to_end` and `to_begin` are currently supported only with default values `None`. + Keyword arguments `to_end` and `to_begin` are currently supported only + with default values `None`. Otherwise the function will be executed sequentially on CPU. Input array data types are limited by supported DPNP :ref:`Data types`. See Also -------- - :obj:`dpnp.diff` : Calculate the n-th discrete difference along the given axis. + :obj:`dpnp.diff` : Calculate the n-th discrete difference along the given + axis. Examples -------- @@ -1196,135 +1175,127 @@ def fabs(x1, **kwargs): return call_origin(numpy.fabs, x1, **kwargs) -def floor( - x, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Round a number to the nearest integer toward minus infinity. - - For full documentation refer to :obj:`numpy.floor`. - - Returns - ------- - out : dpnp.ndarray - The floor of each element of `x`. - - Limitations - ----------- - Parameter `x` is only supported as either :class:`dpnp.ndarray` or :class:`dpctl.tensor.usm_ndarray`. - Parameters `where`, `dtype`, and `subok` are supported with their default values. - Keyword argument `kwargs` is currently unsupported. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by real-value data types. - - See Also - -------- - :obj:`dpnp.ceil` : Compute the ceiling of the input, element-wise. - :obj:`dpnp.trunc` : Return the truncated value of the input, element-wise. - - Notes - ----- - Some spreadsheet programs calculate the "floor-towards-zero", in other words floor(-2.5) == -2. - DPNP instead uses the definition of floor where floor(-2.5) == -3. - - Examples - -------- - >>> import dpnp as np - >>> 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]) - - """ - - return check_nd_call_func( - numpy.floor, - dpnp_floor, - x, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) - - -def floor_divide( - x1, - x2, - /, - out=None, - *, - where=True, - order="K", - dtype=None, - subok=True, - **kwargs, -): - """ - Compute the largest integer smaller or equal to the division of the inputs. - - For full documentation refer to :obj:`numpy.floor_divide`. - - Returns - ------- - out : dpnp.ndarray - The floordivide of each element of `x`. - - Limitations - ----------- - Parameters `x1` and `x2` are supported as either scalar, :class:`dpnp.ndarray` - or :class:`dpctl.tensor.usm_ndarray`, but both `x1` and `x2` can not be scalars at the same time. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Keyword argument `kwargs` is currently unsupported. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. - - See Also - -------- - :obj:`dpnp.remainder` : Remainder complementary to floor_divide. - :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. - - Examples - -------- - >>> import dpnp as np - >>> np.floor_divide(np.array([1, -1, -2, -9]), -2) - array([-1, 0, 1, 4]) +_FLOOR_DOCSTRING = """ +Returns the floor for each element `x_i` for input array `x`. +The floor of the scalar `x` is the largest integer `i`, such that `i <= x`. + +For full documentation refer to :obj:`numpy.floor`. + +Parameters +---------- +x : {dpnp.ndarray, usm_ndarray} + Input array, expected to have a real-valued data type. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +Returns +------- +out : dpnp.ndarray + An array containing the element-wise floor of input array. + The returned array has the same data type as `x`. + +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 +-------- +:obj:`dpnp.ceil` : Compute the ceiling of the input, element-wise. +:obj:`dpnp.trunc` : Return the truncated value of the input, element-wise. - >>> np.floor_divide(np.array([1., 2., 3., 4.]), 2.5) - array([ 0., 0., 1., 1.]) +Notes +----- +Some spreadsheet programs calculate the "floor-towards-zero", in other words floor(-2.5) == -2. +DPNP instead uses the definition of floor where floor(-2.5) == -3. + +Examples +-------- +>>> import dpnp as np +>>> 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]) +""" - The ``//`` operator can be used as a shorthand for ``floor_divide`` on - :class:`dpnp.ndarray`. +floor = DPNPUnaryFunc( + "floor", + ti._floor_result_type, + ti._floor, + _FLOOR_DOCSTRING, + mkl_fn_to_call=vmi._mkl_floor_to_call, + mkl_impl_fn=vmi._floor, +) - >>> x1 = np.array([1., 2., 3., 4.]) - >>> x1 // 2.5 - array([0., 0., 1., 1.]) - """ +_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. + +For full documentation refer to :obj:`numpy.floor_divide`. + +Parameters +---------- +x1 : {dpnp.ndarray, usm_ndarray} + First input array, expected to have numeric data type. +x2 : {dpnp.ndarray, usm_ndarray} + Second input array, also expected to have numeric data type. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +Returns +------- +out : dpnp.ndarray + an array containing the result of element-wise floor division. + The data type of the returned array is determined by the Type + Promotion Rules + +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 +-------- +:obj:`dpnp.remainder` : Remainder complementary to floor_divide. +: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. + +Examples +-------- +>>> import dpnp as np +>>> np.floor_divide(np.array([1, -1, -2, -9]), -2) +array([-1, 0, 1, 4]) + +>>> np.floor_divide(np.array([1., 2., 3., 4.]), 2.5) +array([ 0., 0., 1., 1.]) + +The ``//`` operator can be used as a shorthand for ``floor_divide`` on +:class:`dpnp.ndarray`. + +>>> x1 = np.array([1., 2., 3., 4.]) +>>> x1 // 2.5 +array([0., 0., 1., 1.]) +""" - return check_nd_call_func( - numpy.floor_divide, - dpnp_floor_divide, - x1, - x2, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) +floor_divide = DPNPBinaryFunc( + "floor_divide", + ti._floor_divide_result_type, + ti._floor_divide, + _FLOOR_DIVIDE_DOCSTRING, + binary_inplace_fn=ti._floor_divide_inplace, +) def fmax(x1, x2, /, out=None, *, where=True, dtype=None, subok=True, **kwargs): @@ -1340,20 +1311,26 @@ def fmax(x1, x2, /, out=None, *, where=True, dtype=None, subok=True, **kwargs): Limitations ----------- - Parameters `x1` and `x2` are supported as either scalar, :class:`dpnp.ndarray` - or :class:`dpctl.tensor.usm_ndarray`, but both `x1` and `x2` can not be scalars at the same time. - Parameters `where`, `dtype` and `subok` are supported with their default values. + Parameters `x1` and `x2` are supported as either scalar, + :class:`dpnp.ndarray` or :class:`dpctl.tensor.usm_ndarray`, but both `x1` + and `x2` can not be scalars at the same time. + Parameters `where`, `dtype` and `subok` are supported with their default + values. Keyword argument `kwargs` is currently unsupported. Otherwise the function will be executed sequentially on CPU. Input array data types are limited by real-valued data types. See Also -------- - :obj:`dpnp.maximum` : Element-wise maximum of array elements, propagates NaNs. + :obj:`dpnp.maximum` : Element-wise maximum of array elements, propagates + NaNs. :obj:`dpnp.fmin` : Element-wise minimum of array elements, ignores NaNs. - :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. - :obj:`dpnp.minimum` : Element-wise minimum of array elements, propagates NaNs. + :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. + :obj:`dpnp.minimum` : Element-wise minimum of array elements, propagates + NaNs. :obj:`dpnp.fmod` : Calculate the element-wise remainder of division. Examples @@ -1389,7 +1366,8 @@ def fmax(x1, x2, /, out=None, *, where=True, dtype=None, subok=True, **kwargs): # at least either x1 or x2 has to be an array pass else: - # get USM type and queue to copy scalar from the host memory into a USM allocation + # get USM type and queue to copy scalar from the host memory + # into a USM allocation usm_type, queue = ( get_usm_allocations([x1, x2]) if dpnp.isscalar(x1) or dpnp.isscalar(x2) @@ -1447,20 +1425,26 @@ def fmin(x1, x2, /, out=None, *, where=True, dtype=None, subok=True, **kwargs): Limitations ----------- - Parameters `x1` and `x2` are supported as either scalar, :class:`dpnp.ndarray` - or :class:`dpctl.tensor.usm_ndarray`, but both `x1` and `x2` can not be scalars at the same time. - Parameters `where`, `dtype` and `subok` are supported with their default values. + Parameters `x1` and `x2` are supported as either scalar, + :class:`dpnp.ndarray` or :class:`dpctl.tensor.usm_ndarray`, but both `x1` + and `x2` can not be scalars at the same time. + Parameters `where`, `dtype` and `subok` are supported with their default + values. Keyword argument `kwargs` is currently unsupported. Otherwise the function will be executed sequentially on CPU. Input array data types are limited by real-valued data types. See Also -------- - :obj:`dpnp.minimum` : Element-wise minimum of array elements, propagates NaNs. + :obj:`dpnp.minimum` : Element-wise minimum of array elements, propagates + NaNs. :obj:`dpnp.fmax` : Element-wise maximum of array elements, ignores NaNs. - :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. - :obj:`dpnp.maximum` : Element-wise maximum of array elements, propagates NaNs. + :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. + :obj:`dpnp.maximum` : Element-wise maximum of array elements, propagates + NaNs. :obj:`dpnp.fmod` : Calculate the element-wise remainder of division. Examples @@ -1496,7 +1480,8 @@ def fmin(x1, x2, /, out=None, *, where=True, dtype=None, subok=True, **kwargs): # at least either x1 or x2 has to be an array pass else: - # get USM type and queue to copy scalar from the host memory into a USM allocation + # get USM type and queue to copy scalar from the host memory into + # a USM allocation usm_type, queue = ( get_usm_allocations([x1, x2]) if dpnp.isscalar(x1) or dpnp.isscalar(x2) @@ -1554,9 +1539,11 @@ def fmod(x1, x2, /, out=None, *, where=True, dtype=None, subok=True, **kwargs): Limitations ----------- - Parameters `x1` and `x2` are supported as either scalar, :class:`dpnp.ndarray` - or :class:`dpctl.tensor.usm_ndarray`, but both `x1` and `x2` can not be scalars at the same time. - Parameters `where`, `dtype` and `subok` are supported with their default values. + Parameters `x1` and `x2` are supported as either scalar, + :class:`dpnp.ndarray` or :class:`dpctl.tensor.usm_ndarray`, but both `x1` + and `x2` can not be scalars at the same time. + Parameters `where`, `dtype` and `subok` are supported with their default + values. Keyword argument `kwargs` is currently unsupported. Otherwise the function will be executed sequentially on CPU. Input array data types are limited by supported DPNP :ref:`Data types`. @@ -1605,7 +1592,8 @@ def fmod(x1, x2, /, out=None, *, where=True, dtype=None, subok=True, **kwargs): # at least either x1 or x2 has to be an array pass else: - # get USM type and queue to copy scalar from the host memory into a USM allocation + # get USM type and queue to copy scalar from the host memory into + # a USM allocation usm_type, queue = ( get_usm_allocations([x1, x2]) if dpnp.isscalar(x1) or dpnp.isscalar(x2) @@ -1666,7 +1654,8 @@ def gradient(x1, *varargs, **kwargs): See Also -------- - :obj:`dpnp.diff` : Calculate the n-th discrete difference along the given axis. + :obj:`dpnp.diff` : Calculate the n-th discrete difference along the given + axis. Examples -------- @@ -1696,51 +1685,205 @@ def gradient(x1, *varargs, **kwargs): return call_origin(numpy.gradient, x1, *varargs, **kwargs) -def imag(val): - """ - Return the imaginary part of the complex argument. - - For full documentation refer to :obj:`numpy.imag`. - - Parameters - ---------- - x : {dpnp.ndarray, usm_ndarray} - Input array. +_IMAG_DOCSTRING = """ +Computes imaginary part of each element `x_i` for 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. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +Returns +------- +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 + 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. + +See Also +-------- +:obj:`dpnp.real` : Return the real part of the complex argument. +:obj:`dpnp.conj` : Return the complex conjugate, element-wise. +:obj:`dpnp.conjugate` : Return the complex conjugate, element-wise. + +Examples +-------- +>>> import dpnp as np +>>> a = np.array([1+2j, 3+4j, 5+6j]) +>>> a.imag +array([2., 4., 6.]) + +>>> a.imag = np.array([8, 10, 12]) +>>> a +array([1. +8.j, 3.+10.j, 5.+12.j]) + +>>> np.imag(np.array(1 + 1j)) +array(1.) +""" - Returns - ------- - out : dpnp.ndarray - The imaginary component of the complex argument. If `val` is real, - the type of `val` is used for the output. If `val` has complex - elements, the returned type is float. +imag = DPNPUnaryFunc( + "imag", + ti._imag_result_type, + ti._imag, + _IMAG_DOCSTRING, +) - See Also - -------- - :obj:`dpnp.real` : Return the real part of the complex argument. - :obj:`dpnp.conj` : Return the complex conjugate, element-wise. - :obj:`dpnp.conjugate` : Return the complex conjugate, element-wise. - Examples - -------- - >>> import dpnp as np - >>> a = np.array([1+2j, 3+4j, 5+6j]) - >>> a.imag - array([2., 4., 6.]) +_MAXIMUM_DOCSTRING = """ +Compares two input arrays `x1` and `x2` and returns +a new array containing the element-wise maxima. + +For full documentation refer to :obj:`numpy.maximum`. + +Parameters +---------- +x1 : {dpnp.ndarray, usm_ndarray} + First input array, expected to have numeric data type. +x2 : {dpnp.ndarray, usm_ndarray} + Second input array, also expected to have numeric data type. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +Returns +------- +out : dpnp.ndarray + An array containing the element-wise maxima. The data type of + the returned array is determined by the Type Promotion Rules. + +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 +-------- +:obj:`dpnp.minimum` : Element-wise minimum of two arrays, propagates NaNs. +:obj:`dpnp.fmax` : Element-wise maximum of two arrays, ignores NaNs. +: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. +:obj:`dpnp.fmin` : Element-wise minimum of two arrays, ignores NaNs. +: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. + +Examples +-------- +>>> import dpnp as np +>>> x1 = np.array([2, 3, 4]) +>>> x2 = np.array([1, 5, 2]) +>>> np.maximum(x1, x2) +array([2, 5, 4]) + +>>> x1 = np.eye(2) +>>> x2 = np.array([0.5, 2]) +>>> np.maximum(x1, x2) # broadcasting +array([[1. , 2. ], + [0.5, 2. ]]) + +>>> x1 = np.array([np.nan, 0, np.nan]) +>>> x2 = np.array([0, np.nan, np.nan]) +>>> np.maximum(x1, x2) +array([nan, nan, nan]) + +>>> np.maximum(np.array(np.Inf), 1) +array(inf) +""" - >>> a.imag = np.array([8, 10, 12]) - >>> a - array([1. +8.j, 3.+10.j, 5.+12.j]) +maximum = DPNPBinaryFunc( + "maximum", + ti._maximum_result_type, + ti._maximum, + _MAXIMUM_DOCSTRING, +) - >>> np.imag(np.array(1 + 1j)) - array(1.) - """ +_MINIMUM_DOCSTRING = """ +Compares two input arrays `x1` and `x2` and returns +a new array containing the element-wise minima. + +For full documentation refer to :obj:`numpy.minimum`. + +Parameters +---------- +x1 : {dpnp.ndarray, usm_ndarray} + First input array, expected to have numeric data type. +x2 : {dpnp.ndarray, usm_ndarray} + Second input array, also expected to have numeric data type. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +Returns +------- +out : dpnp.ndarray + An array containing the element-wise minima. The data type of + the returned array is determined by the Type Promotion Rules. + +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 +-------- +:obj:`dpnp.maximum` : Element-wise maximum of two arrays, propagates NaNs. +:obj:`dpnp.fmin` : Element-wise minimum of two arrays, ignores NaNs. +: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. +:obj:`dpnp.fmax` : Element-wise maximum of two arrays, ignores NaNs. +: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. + +Examples +-------- +>>> import dpnp as np +>>> x1 = np.array([2, 3, 4]) +>>> x2 = np.array([1, 5, 2]) +>>> np.minimum(x1, x2) +array([1, 3, 2]) + +>>> x1 = np.eye(2) +>>> x2 = np.array([0.5, 2]) +>>> np.minimum(x1, x2) # broadcasting +array([[0.5, 0. ], + [0. , 1. ]] + +>>> x1 = np.array([np.nan, 0, np.nan]) +>>> x2 = np.array([0, np.nan, np.nan]) +>>> np.minimum(x1, x2) +array([nan, nan, nan]) + +>>> np.minimum(np.array(-np.Inf), 1) +array(-inf) +""" - dpnp.check_supported_arrays_type(val) - return dpnp_imag(val) +minimum = DPNPBinaryFunc( + "minimum", + ti._minimum_result_type, + ti._minimum, + _MINIMUM_DOCSTRING, +) -def maximum( +def mod( x1, x2, /, @@ -1753,61 +1896,39 @@ def maximum( **kwargs, ): """ - Element-wise maximum of array elements. + Compute element-wise remainder of division. - For full documentation refer to :obj:`numpy.maximum`. + For full documentation refer to :obj:`numpy.mod`. Returns ------- out : dpnp.ndarray - The maximum of `x1` and `x2`, element-wise, propagating NaNs. + The element-wise remainder of the quotient `floor_divide(x1, x2)`. Limitations ----------- - Parameters `x1` and `x2` are supported as either scalar, :class:`dpnp.ndarray` - or :class:`dpctl.tensor.usm_ndarray`, but both `x1` and `x2` can not be scalars at the same time. - Parameters `where`, `dtype` and `subok` are supported with their default values. + Parameters `x1` and `x2` are supported as either scalar, + :class:`dpnp.ndarray` or :class:`dpctl.tensor.usm_ndarray`, but both `x1` + and `x2` can not be scalars at the same time. + Parameters `where`, `dtype` and `subok` are supported with their default + values. Keyword argument `kwargs` is currently unsupported. Otherwise the function will be executed sequentially on CPU. Input array data types are limited by supported DPNP :ref:`Data types`. See Also -------- - :obj:`dpnp.minimum` : Element-wise minimum of two arrays, propagates NaNs. - :obj:`dpnp.fmax` : Element-wise maximum of two arrays, ignores NaNs. - :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. - :obj:`dpnp.fmin` : Element-wise minimum of two arrays, ignores NaNs. - :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. - - Examples - -------- - >>> import dpnp as np - >>> x1 = np.array([2, 3, 4]) - >>> x2 = np.array([1, 5, 2]) - >>> np.maximum(x1, x2) - array([2, 5, 4]) - - >>> x1 = np.eye(2) - >>> x2 = np.array([0.5, 2]) - >>> np.maximum(x1, x2) # broadcasting - array([[1. , 2. ], - [0.5, 2. ]]) - - >>> x1 = np.array([np.nan, 0, np.nan]) - >>> x2 = np.array([0, np.nan, np.nan]) - >>> np.maximum(x1, x2) - array([nan, nan, nan]) + :obj:`dpnp.fmod` : Calculate the element-wise remainder of division + :obj:`dpnp.remainder` : Remainder complementary to floor_divide. + :obj:`dpnp.divide` : Standard division. - >>> np.maximum(np.array(np.Inf), 1) - array(inf) + Notes + ----- + This function works the same as :obj:`dpnp.remainder`. """ - return check_nd_call_func( - numpy.maximum, - dpnp_maximum, + return dpnp.remainder( x1, x2, out=out, @@ -1819,1017 +1940,801 @@ def maximum( ) -def minimum( - x1, - x2, - /, - out=None, - *, - where=True, - order="K", - dtype=None, - subok=True, - **kwargs, -): +def modf(x1, **kwargs): """ - Element-wise minimum of array elements. - - For full documentation refer to :obj:`numpy.minimum`. + Return the fractional and integral parts of an array, element-wise. - Returns - ------- - out : dpnp.ndarray - The minimum of `x1` and `x2`, element-wise, propagating NaNs. + For full documentation refer to :obj:`numpy.modf`. Limitations ----------- - Parameters `x1` and `x2` are supported as either scalar, :class:`dpnp.ndarray` - or :class:`dpctl.tensor.usm_ndarray`, but both `x1` and `x2` can not be scalars at the same time. - Parameters `where`, `dtype` and `subok` are supported with their default values. + Parameter `x` is supported as :obj:`dpnp.ndarray`. Keyword argument `kwargs` is currently unsupported. Otherwise the function will be executed sequentially on CPU. Input array data types are limited by supported DPNP :ref:`Data types`. - See Also - -------- - :obj:`dpnp.maximum` : Element-wise maximum of two arrays, propagates NaNs. - :obj:`dpnp.fmin` : Element-wise minimum of two arrays, ignores NaNs. - :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. - :obj:`dpnp.fmax` : Element-wise maximum of two arrays, ignores NaNs. - :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. - Examples -------- >>> import dpnp as np - >>> x1 = np.array([2, 3, 4]) - >>> x2 = np.array([1, 5, 2]) - >>> np.minimum(x1, x2) - array([1, 3, 2]) + >>> a = np.array([1, 2]) + >>> result = np.modf(a) + >>> [[x for x in y] for y in result ] + [[1.0, 2.0], [0.0, 0.0]] - >>> x1 = np.eye(2) - >>> x2 = np.array([0.5, 2]) - >>> np.minimum(x1, x2) # broadcasting - array([[0.5, 0. ], - [0. , 1. ]] + """ - >>> x1 = np.array([np.nan, 0, np.nan]) - >>> x2 = np.array([0, np.nan, np.nan]) - >>> np.minimum(x1, x2) - array([nan, nan, nan]) + x1_desc = dpnp.get_dpnp_descriptor(x1, copy_when_nondefault_queue=False) + if x1_desc and not kwargs: + return dpnp_modf(x1_desc) - >>> np.minimum(np.array(-np.Inf), 1) - array(-inf) + return call_origin(numpy.modf, x1, **kwargs) - """ - return check_nd_call_func( - numpy.minimum, - dpnp_minimum, - x1, - x2, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **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`. + +For full documentation refer to :obj:`numpy.multiply`. + +Parameters +---------- +x1 : {dpnp.ndarray, usm_ndarray} + First input array, expected to have numeric data type. +x2 : {dpnp.ndarray, usm_ndarray} + Second input array, also expected to have numeric data type. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +Returns +------- +out : dpnp.ndarray + an array containing the result of element-wise multiplication. The data type + of the returned array is determined by the Type Promotion Rules. + +Limitations +----------- +Parameters `where` and `subok` are supported with their default values. +Keyword argument `kwargs` is currently unsupported. +Otherwise ``NotImplementedError`` exception will be raised. +Notes +----- +Equivalent to `x1` * `x2` in terms of array broadcasting. + +Examples +-------- +>>> import dpnp as np +>>> a = np.array([1, 2, 3, 4, 5]) +>>> np.multiply(a, a) +array([ 1, 4, 9, 16, 25])] + +>>> x1 = np.arange(9.0).reshape((3, 3)) +>>> x2 = np.arange(3.0) +>>> np.multiply(x1, x2) +array([[ 0., 1., 4.], + [ 0., 4., 10.], + [ 0., 7., 16.]]) + +The ``*`` operator can be used as a shorthand for ``multiply`` on +:class:`dpnp.ndarray`. + +>>> x1 * x2 +array([[ 0., 1., 4.], + [ 0., 4., 10.], + [ 0., 7., 16.]]) +""" -def mod( - x1, - x2, - /, - out=None, - *, - where=True, - order="K", - dtype=None, - subok=True, - **kwargs, -): - """ - Compute element-wise remainder of division. - - For full documentation refer to :obj:`numpy.mod`. - - Returns - ------- - out : dpnp.ndarray - The element-wise remainder of the quotient `floor_divide(x1, x2)`. - - Limitations - ----------- - Parameters `x1` and `x2` are supported as either scalar, :class:`dpnp.ndarray` - or :class:`dpctl.tensor.usm_ndarray`, but both `x1` and `x2` can not be scalars at the same time. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Keyword argument `kwargs` is currently unsupported. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. - - See Also - -------- - :obj:`dpnp.fmod` : Calculate the element-wise remainder of division - :obj:`dpnp.remainder` : Remainder complementary to floor_divide. - :obj:`dpnp.divide` : Standard division. - - Notes - ----- - This function works the same as :obj:`dpnp.remainder`. - - """ - - return dpnp.remainder( - x1, - x2, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) - - -def modf(x1, **kwargs): - """ - Return the fractional and integral parts of an array, element-wise. - - For full documentation refer to :obj:`numpy.modf`. - - Limitations - ----------- - Parameter `x` is supported as :obj:`dpnp.ndarray`. - Keyword argument `kwargs` is currently unsupported. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. - - Examples - -------- - >>> import dpnp as np - >>> a = np.array([1, 2]) - >>> result = np.modf(a) - >>> [[x for x in y] for y in result ] - [[1.0, 2.0], [0.0, 0.0]] - - - """ - - x1_desc = dpnp.get_dpnp_descriptor(x1, copy_when_nondefault_queue=False) - if x1_desc and not kwargs: - return dpnp_modf(x1_desc) - - return call_origin(numpy.modf, x1, **kwargs) - - -def multiply( - x1, - x2, - /, - out=None, - *, - where=True, - order="K", - dtype=None, - subok=True, - **kwargs, -): - """ - Multiply arguments element-wise. - - For full documentation refer to :obj:`numpy.multiply`. - - Returns - ------- - out : {dpnp.ndarray, scalar} - The product of `x1` and `x2`, element-wise. - - Limitations - ----------- - Parameters `x1` and `x2` are supported as either scalar, :class:`dpnp.ndarray` - or :class:`dpctl.tensor.usm_ndarray`, but both `x1` and `x2` can not be scalars at the same time. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Keyword argument `kwargs` is currently unsupported. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. - - Notes - ----- - Equivalent to `x1` * `x2` in terms of array broadcasting. - - Examples - -------- - >>> import dpnp as np - >>> a = np.array([1, 2, 3, 4, 5]) - >>> np.multiply(a, a) - array([ 1, 4, 9, 16, 25])] - - >>> x1 = np.arange(9.0).reshape((3, 3)) - >>> x2 = np.arange(3.0) - >>> np.multiply(x1, x2) - array([[ 0., 1., 4.], - [ 0., 4., 10.], - [ 0., 7., 16.]]) - - The ``*`` operator can be used as a shorthand for ``multiply`` on - :class:`dpnp.ndarray`. - - >>> x1 * x2 - array([[ 0., 1., 4.], - [ 0., 4., 10.], - [ 0., 7., 16.]]) - """ - - return check_nd_call_func( - numpy.multiply, - dpnp_multiply, - x1, - x2, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) - - -def negative( - x, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Numerical negative, element-wise. - - For full documentation refer to :obj:`numpy.negative`. - - Returns - ------- - out : dpnp.ndarray - The numerical negative of each element of `x`. - - Limitations - ----------- - Parameters `x` is only supported as either :class:`dpnp.ndarray` or :class:`dpctl.tensor.usm_ndarray`. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Keyword argument `kwargs` is currently unsupported. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. - - See Also - -------- - :obj:`dpnp.positive` : Return the numerical positive of each element of `x`. - :obj:`dpnp.copysign` : Change the sign of `x1` to that of `x2`, element-wise. - - Examples - -------- - >>> import dpnp as np - >>> np.negative(np.array([1, -1])) - array([-1, 1]) - - The ``-`` operator can be used as a shorthand for ``negative`` on - :class:`dpnp.ndarray`. - - >>> x = np.array([1., -1.]) - >>> -x - array([-1., 1.]) - """ - - return check_nd_call_func( - numpy.negative, - dpnp_negative, - x, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) - - -def positive( - x, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Numerical positive, element-wise. - - For full documentation refer to :obj:`numpy.positive`. - - Returns - ------- - out : dpnp.ndarray - The numerical positive of each element of `x`. - - Limitations - ----------- - Parameters `x` is only supported as either :class:`dpnp.ndarray` or :class:`dpctl.tensor.usm_ndarray`. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Keyword argument `kwargs` is currently unsupported. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. - - See Also - -------- - :obj:`dpnp.negative` : Return the numerical negative of each element of `x`. - :obj:`dpnp.copysign` : Change the sign of `x1` to that of `x2`, element-wise. - - Note - ---- - Equivalent to `x.copy()`, but only defined for types that support arithmetic. - - Examples - -------- - >>> import dpnp as np - >>> np.positive(np.array([1., -1.])) - array([ 1., -1.]) - - The ``+`` operator can be used as a shorthand for ``positive`` on - :class:`dpnp.ndarray`. - - >>> x = np.array([1., -1.]) - >>> +x - array([ 1., -1.]) - """ - - return check_nd_call_func( - numpy.positive, - dpnp_positive, - x, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) - - -def power( - x1, - x2, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - First array elements raised to powers from second array, element-wise. - - An integer type (of either negative or positive value, but not zero) - raised to a negative integer power will return an array of zeroes. - - For full documentation refer to :obj:`numpy.power`. - - Returns - ------- - out : dpnp.ndarray - The bases in `x1` raised to the exponents in `x2`. - - Limitations - ----------- - Parameters `x1` and `x2` are supported as either scalar, :class:`dpnp.ndarray` - or :class:`dpctl.tensor.usm_ndarray`, but both `x1` and `x2` can not be scalars at the same time. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Keyword argument `kwargs` is currently unsupported. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. - - See Also - -------- - :obj:`dpnp.fmax` : Element-wise maximum of array elements. - :obj:`dpnp.fmin` : Element-wise minimum of array elements. - :obj:`dpnp.fmod` : Calculate the element-wise remainder of division. - - - Examples - -------- - >>> import dpnp as dp - >>> a = dp.arange(6) - >>> dp.power(a, 3) - array([ 0, 1, 8, 27, 64, 125]) - - Raise the bases to different exponents. - - >>> b = dp.array([1.0, 2.0, 3.0, 3.0, 2.0, 1.0]) - >>> dp.power(a, b) - array([ 0., 1., 8., 27., 16., 5.]) - - The effect of broadcasting. - - >>> c = dp.array([[1, 2, 3, 3, 2, 1], [1, 2, 3, 3, 2, 1]]) - >>> dp.power(a, c) - array([[ 0, 1, 8, 27, 16, 5], - [ 0, 1, 8, 27, 16, 5]]) - - The ``**`` operator can be used as a shorthand for ``power`` on - :class:`dpnp.ndarray`. - - >>> b = dp.array([1, 2, 3, 3, 2, 1]) - >>> a = dp.arange(6) - >>> a ** b - array([ 0, 1, 8, 27, 16, 5]) - - Negative values raised to a non-integral value will result in ``nan``. - - >>> d = dp.array([-1.0, -4.0]) - >>> dp.power(d, 1.5) - array([nan, nan]) - - """ - - return check_nd_call_func( - numpy.power, - dpnp_power, - x1, - x2, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) - - -def prod( - a, - axis=None, - dtype=None, - out=None, - keepdims=False, - initial=None, - where=True, -): - """ - Return the product of array elements over a given axis. - - For full documentation refer to :obj:`numpy.prod`. - - Returns - ------- - out : dpnp.ndarray - A new array holding the result is returned unless `out` is specified, in which case it is returned. - - Limitations - ----------- - Input array is only supported as either :class:`dpnp.ndarray` or :class:`dpctl.tensor.usm_ndarray`. - Parameters `initial`, and `where` are only supported with their default values. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by DPNP :ref:`Data types`. - - See Also - -------- - :obj:`dpnp.nanprod` : Return the product of array elements over a given axis treating Not a Numbers (NaNs) as ones. - - Examples - -------- - >>> import dpnp as np - >>> np.prod(np.array([1, 2])) - array(2) - - >>> a = np.array([[1, 2], [3, 4]]) - >>> np.prod(a) - array(24) - - >>> np.prod(a, axis=1) - array([ 2, 12]) - >>> np.prod(a, axis=0) - array([3, 8]) - - >>> x = np.array([1, 2, 3], dtype=np.int8) - >>> np.prod(x).dtype == int - True - - """ - - if initial is not None: - raise NotImplementedError( - "initial keyword argument is only supported with its default value." - ) - elif where is not True: - raise NotImplementedError( - "where keyword argument is only supported with its default value." - ) - else: - dpt_array = dpnp.get_usm_ndarray(a) - result = dpnp_array._create_from_usm_ndarray( - dpt.prod(dpt_array, axis=axis, dtype=dtype, keepdims=keepdims) - ) - - return dpnp.get_result_array(result, out) - - -def proj( - x, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Returns the projection of a number onto the Riemann sphere. - - For all infinite complex numbers (including the cases where one component is infinite and the other is `NaN`), - the function returns `(inf, 0.0)` or `(inf, -0.0)`. - For finite complex numbers, the input is returned. - All real-valued numbers are treated as complex numbers with positive zero imaginary part. - - Returns - ------- - out : dpnp.ndarray - The projection of each element of `x`. - - Limitations - ----------- - Parameters `x` is only supported as either :class:`dpnp.ndarray` or :class:`dpctl.tensor.usm_ndarray`. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Keyword argument `kwargs` is currently unsupported. - Input array data types are limited by supported DPNP :ref:`Data types`. - - See Also - -------- - :obj:`dpnp.absolute` : Returns the magnitude of a complex number, element-wise. - :obj:`dpnp.conj` : Return the complex conjugate, element-wise. - - Examples - -------- - >>> import dpnp as np - >>> np.proj(np.array([1, -2.3, 2.1-1.7j])) - array([ 1. +0.j, -2.3+0.j, 2.1-1.7.j]) - - >>> 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]) - - """ - - return check_nd_call_func( - None, - dpnp_proj, - x, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) - - -def real(val): - """ - Return the real part of the complex argument. - - For full documentation refer to :obj:`numpy.real`. - - Parameters - ---------- - x : {dpnp.ndarray, usm_ndarray} - Input array. - - Returns - ------- - out : dpnp.ndarray - The real component of the complex argument. If `val` is real, - the type of `val` is used for the output. If `val` has complex - elements, the returned type is float. - - See Also - -------- - :obj:`dpnp.imag` : Return the imaginary part of the complex argument. - :obj:`dpnp.conj` : Return the complex conjugate, element-wise. - :obj:`dpnp.conjugate` : Return the complex conjugate, element-wise. - - Examples - -------- - >>> import dpnp as np - >>> a = np.array([1+2j, 3+4j, 5+6j]) - >>> a.real - array([1., 3., 5.]) - - >>> a.real = 9 - >>> a - array([9.+2.j, 9.+4.j, 9.+6.j]) - - >>> a.real = np.array([9, 8, 7]) - >>> a - array([9.+2.j, 8.+4.j, 7.+6.j]) - - >>> np.real(np.array(1 + 1j)) - array(1.) - - """ - - dpnp.check_supported_arrays_type(val) - if dpnp.issubsctype(val.dtype, dpnp.complexfloating): - return dpnp_real(val) - else: - return val - - -def remainder( - x1, - x2, - /, - out=None, - *, - where=True, - order="K", - dtype=None, - subok=True, - **kwargs, -): - """ - Return element-wise remainder of division. - - For full documentation refer to :obj:`numpy.remainder`. - - Returns - ------- - out : dpnp.ndarray - The element-wise remainder of the quotient `floor_divide(x1, x2)`. - - Limitations - ----------- - Parameters `x1` and `x2` are supported as either scalar, :class:`dpnp.ndarray` - or :class:`dpctl.tensor.usm_ndarray`, but both `x1` and `x2` can not be scalars at the same time. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Keyword argument `kwargs` is currently unsupported. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. - - See Also - -------- - :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.mod` : Calculate the element-wise remainder of division. - - Examples - -------- - >>> import dpnp as np - >>> np.remainder(np.array([4, 7]), np.array([2, 3])) - array([0, 1]) - - >>> np.remainder(np.arange(7), 5) - array([0, 1, 2, 3, 4, 0, 1]) - - The ``%`` operator can be used as a shorthand for ``remainder`` on - :class:`dpnp.ndarray`. - - >>> x1 = np.arange(7) - >>> x1 % 5 - array([0, 1, 2, 3, 4, 0, 1]) - """ - - return check_nd_call_func( - numpy.remainder, - dpnp_remainder, - x1, - x2, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) - - -def rint( - x, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Round elements of the array to the nearest integer. +multiply = DPNPBinaryFunc( + "multiply", + ti._multiply_result_type, + ti._multiply, + _MULTIPLY_DOCSTRING, + mkl_fn_to_call=vmi._mkl_mul_to_call, + mkl_impl_fn=vmi._mul, + binary_inplace_fn=ti._multiply_inplace, +) - For full documentation refer to :obj:`numpy.rint`. - Returns - ------- - out : dpnp.ndarray - The rounded value of elements of the array to the nearest integer. +_NEGATIVE_DOCSTRING = """ +Computes the numerical negative for each element `x_i` of 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. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +Returns +------- +out : dpnp.ndarray + An array containing the negative of `x`. + +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 +-------- +:obj:`dpnp.positive` : Return the numerical positive of each element of `x`. +:obj:`dpnp.copysign` : Change the sign of `x1` to that of `x2`, element-wise. + +Examples +-------- +>>> import dpnp as np +>>> np.negative(np.array([1, -1])) +array([-1, 1]) + +The ``-`` operator can be used as a shorthand for ``negative`` on +:class:`dpnp.ndarray`. + +>>> x = np.array([1., -1.]) +>>> -x +array([-1., 1.]) +""" - Limitations - ----------- - Parameter `x` is only supported as either :class:`dpnp.ndarray` or :class:`dpctl.tensor.usm_ndarray`. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Keyword argument `kwargs` is currently unsupported. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. +negative = DPNPUnaryFunc( + "negative", + ti._negative_result_type, + ti._negative, + _NEGATIVE_DOCSTRING, + acceptance_fn=acceptance_fn_negative, +) - See Also - -------- - :obj:`dpnp.round` : Evenly round to the given number of decimals. - :obj:`dpnp.ceil` : Compute the ceiling of the input, element-wise. - :obj:`dpnp.floor` : Return the floor of the input, element-wise. - :obj:`dpnp.trunc` : Return the truncated value of the input, element-wise. - Examples - -------- - >>> import dpnp as np - >>> 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.]) +_POSITIVE_DOCSTRING = """ +Computes the numerical positive for each element `x_i` of 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. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +Returns +------- +out : dpnp.ndarray + An array containing the positive of `x`. + +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 +-------- +:obj:`dpnp.negative` : Return the numerical negative of each element of `x`. +:obj:`dpnp.copysign` : Change the sign of `x1` to that of `x2`, element-wise. + +Note +---- +Equivalent to `x.copy()`, but only defined for types that support arithmetic. + +Examples +-------- +>>> import dpnp as np +>>> np.positive(np.array([1., -1.])) +array([ 1., -1.]) + +The ``+`` operator can be used as a shorthand for ``positive`` on +:class:`dpnp.ndarray`. + +>>> x = np.array([1., -1.]) +>>> +x +array([ 1., -1.]) +""" - """ +positive = DPNPUnaryFunc( + "positive", + ti._positive_result_type, + ti._positive, + _POSITIVE_DOCSTRING, + acceptance_fn=acceptance_fn_positive, +) - return check_nd_call_func( - numpy.rint, - dpnp_round, - x, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) + +_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`. + +For full documentation refer to :obj:`numpy.power`. + +Parameters +---------- +x1 : {dpnp.ndarray, usm_ndarray} + First input array, expected to have numeric data type. +x2 : {dpnp.ndarray, usm_ndarray} + Second input array, also expected to have numeric data type. +out : {None, dpnp.ndarray}, optional + Output array to populate. Array must have the correct + shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Output array, if parameter `out` is ``None``. + Default: "K". + +Returns +------- +out : dpnp.ndarray + An array containing the result of element-wise of raising each element + to a specified power. + The data type of the returned array is determined by the Type Promotion Rules. + +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 +-------- +:obj:`dpnp.fmax` : Element-wise maximum of array elements. +:obj:`dpnp.fmin` : Element-wise minimum of array elements. +:obj:`dpnp.fmod` : Calculate the element-wise remainder of division. + + +Examples +-------- +>>> import dpnp as dp +>>> a = dp.arange(6) +>>> dp.power(a, 3) +array([ 0, 1, 8, 27, 64, 125]) + +Raise the bases to different exponents. + +>>> b = dp.array([1.0, 2.0, 3.0, 3.0, 2.0, 1.0]) +>>> dp.power(a, b) +array([ 0., 1., 8., 27., 16., 5.]) + +The effect of broadcasting. + +>>> c = dp.array([[1, 2, 3, 3, 2, 1], [1, 2, 3, 3, 2, 1]]) +>>> dp.power(a, c) +array([[ 0, 1, 8, 27, 16, 5], + [ 0, 1, 8, 27, 16, 5]]) + +The ``**`` operator can be used as a shorthand for ``power`` on +:class:`dpnp.ndarray`. + +>>> b = dp.array([1, 2, 3, 3, 2, 1]) +>>> a = dp.arange(6) +>>> a ** b +array([ 0, 1, 8, 27, 16, 5]) + +Negative values raised to a non-integral value will result in ``nan``. + +>>> d = dp.array([-1.0, -4.0]) +>>> dp.power(d, 1.5) +array([nan, nan]) +""" + +power = DPNPBinaryFunc( + "power", + ti._pow_result_type, + ti._pow, + _POWER_DOCSTRING, + mkl_fn_to_call=vmi._mkl_pow_to_call, + mkl_impl_fn=vmi._pow, + binary_inplace_fn=ti._pow_inplace, +) -def round(x, decimals=0, out=None): +def prod( + a, + axis=None, + dtype=None, + out=None, + keepdims=False, + initial=None, + where=True, +): """ - Evenly round to the given number of decimals. + Return the product of array elements over a given axis. - For full documentation refer to :obj:`numpy.round`. + For full documentation refer to :obj:`numpy.prod`. Returns ------- out : dpnp.ndarray - The rounded value of elements of the array. + A new array holding the result is returned unless `out` is specified, + in which case it is returned. Limitations ----------- - Parameter `x` is only supported as either :class:`dpnp.ndarray` or :class:`dpctl.tensor.usm_ndarray`. - Parameters `decimals` is supported with its default value. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. + Input array is only supported as either :class:`dpnp.ndarray` or + :class:`dpctl.tensor.usm_ndarray`. + Parameters `initial`, and `where` are only supported with their default + values. + Otherwise ``NotImplementedError`` exception will be raised. + Input array data types are limited by DPNP :ref:`Data types`. See Also -------- - :obj:`dpnp.around` : Equivalent function; see for details. - :obj:`dpnp.ndarray.round` : Equivalent function. - :obj:`dpnp.rint` : Round elements of the array to the nearest integer. - :obj:`dpnp.ceil` : Compute the ceiling of the input, element-wise. - :obj:`dpnp.floor` : Return the floor of the input, element-wise. - :obj:`dpnp.trunc` : Return the truncated value of the input, element-wise. + :obj:`dpnp.nanprod` : Return the product of array elements over a given + axis treating Not a Numbers (NaNs) as ones. Examples -------- >>> import dpnp as np - >>> np.round(np.array([0.37, 1.64])) - array([0., 2.]) - >>> np.round(np.array([0.37, 1.64]), decimals=1) - array([0.4, 1.6]) - >>> np.round(np.array([.5, 1.5, 2.5, 3.5, 4.5])) # rounds to nearest even value - array([0., 2., 2., 4., 4.]) - >>> np.round(np.array([1,2,3,11]), decimals=1) # ndarray of ints is returned - array([ 1, 2, 3, 11]) - >>> np.round(np.array([1,2,3,11]), decimals=-1) - array([ 0, 0, 0, 10]) + >>> np.prod(np.array([1, 2])) + array(2) - """ + >>> a = np.array([[1, 2], [3, 4]]) + >>> np.prod(a) + array(24) - if decimals != 0: - pass - elif dpnp.isscalar(x): - # input has to be an array - pass - else: - return dpnp_round(x, out=out) - return call_origin(numpy.round, x, decimals=decimals, out=out) + >>> np.prod(a, axis=1) + array([ 2, 12]) + >>> np.prod(a, axis=0) + array([3, 8]) + >>> x = np.array([1, 2, 3], dtype=np.int8) + >>> np.prod(x).dtype == int + True -def sign( - x, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): """ - Returns an element-wise indication of the sign of a number. - For full documentation refer to :obj:`numpy.sign`. + if initial is not None: + raise NotImplementedError( + "initial keyword argument is only supported with its default value." + ) + if where is not True: + raise NotImplementedError( + "where keyword argument is only supported with its default value." + ) + dpt_array = dpnp.get_usm_ndarray(a) + result = dpnp_array._create_from_usm_ndarray( + dpt.prod(dpt_array, axis=axis, dtype=dtype, keepdims=keepdims) + ) - Returns - ------- - out : dpnp.ndarray - The indication of the sign of each element of `x`. + return dpnp.get_result_array(result, out) + + +_PROJ_DOCSTRING = """ +Computes projection of each element `x_i` for input array `x`. + +Parameters +---------- +x : {dpnp.ndarray, usm_ndarray} + Input array, expected to have numeric data type. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +Returns +------- +out : dpnp.ndarray + An array containing the element-wise projection. + The returned array has the same data type as `x`. + +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 +-------- +:obj:`dpnp.absolute` : Returns the magnitude of a complex number, element-wise. +:obj:`dpnp.conj` : Return the complex conjugate, element-wise. + +Examples +-------- +>>> import dpnp as np +>>> np.proj(np.array([1, -2.3, 2.1-1.7j])) +array([ 1. +0.j, -2.3+0.j, 2.1-1.7.j]) + +>>> 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]) +""" - Limitations - ----------- - Parameters `x` is only supported as either :class:`dpnp.ndarray` or :class:`dpctl.tensor.usm_ndarray`. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Keyword argument `kwargs` is currently unsupported. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. - However, if the input array data type is complex, the function will be executed sequentially on CPU. +proj = DPNPUnaryFunc( + "proj", + ti._proj_result_type, + ti._proj, + _PROJ_DOCSTRING, +) - See Also - -------- - :obj:`dpnp.signbit` : Returns element-wise `True` where signbit is set (less than zero). - Examples - -------- - >>> import dpnp as np - >>> np.sign(np.array([-5., 4.5])) - array([-1.0, 1.0]) - >>> np.sign(np.array(0)) - array(0) - >>> np.sign(np.array(5-2j)) - array([1+0j]) +_REAL_DOCSTRING = """ +Computes real part of each element `x_i` for input array `x`. - """ +For full documentation refer to :obj:`numpy.real`. - if numpy.iscomplexobj(x): - return call_origin( - numpy.sign, - x, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) - else: - return check_nd_call_func( - numpy.sign, - dpnp_sign, - x, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) +Parameters +---------- +x : {dpnp.ndarray, usm_ndarray} + Input array, expected to have numeric data type. +Returns +------- +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 + 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. +""" -def signbit( - x, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Returns element-wise `True` where signbit is set (less than zero). +real = DPNPReal( + "real", + ti._real_result_type, + ti._real, + _REAL_DOCSTRING, +) - For full documentation refer to :obj:`numpy.signbit`. - Returns - ------- - out : dpnp.ndarray - A boolean array with indication of the sign of each element of `x`. +_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`. +This function is equivalent to the Python modulus operator. + +For full documentation refer to :obj:`numpy.remainder`. + +Parameters +---------- +x1 : {dpnp.ndarray, usm_ndarray} + First input array, expected to have a real-valued data type. +x2 : {dpnp.ndarray, usm_ndarray} + Second input array, also expected to have a real-valued data type. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +Returns +------- +out : dpnp.ndarray + an array containing the element-wise remainders. The data type of + the returned array is determined by the Type Promotion Rules. + +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 +-------- +: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.mod` : Calculate the element-wise remainder of division. + +Examples +-------- +>>> import dpnp as np +>>> np.remainder(np.array([4, 7]), np.array([2, 3])) +array([0, 1]) + +>>> np.remainder(np.arange(7), 5) +array([0, 1, 2, 3, 4, 0, 1]) + +The ``%`` operator can be used as a shorthand for ``remainder`` on +:class:`dpnp.ndarray`. + +>>> x1 = np.arange(7) +>>> x1 % 5 +array([0, 1, 2, 3, 4, 0, 1]) +""" - Limitations - ----------- - Parameters `x` is only supported as either :class:`dpnp.ndarray` or :class:`dpctl.tensor.usm_ndarray`. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Keyword argument `kwargs` is currently unsupported. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported real-valued data types. +remainder = DPNPBinaryFunc( + "remainder", + ti._remainder_result_type, + ti._remainder, + _REMAINDER_DOCSTRING, + binary_inplace_fn=ti._remainder_inplace, +) - See Also - -------- - :obj:`dpnp.sign` : Returns an element-wise indication of the sign of a number. - Examples - -------- - >>> import dpnp as np - >>> np.signbit(np.array([-1.2])) - array([True]) +_RINT_DOCSTRING = """ +Round elements of the array to the nearest integer. + +For full documentation refer to :obj:`numpy.rint`. + +Parameters +---------- +x : {dpnp.ndarray, usm_ndarray} + Input array, expected to have numeric data type. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +Returns +------- +out : dpnp.ndarray + An array containing the element-wise rounded value. The data type + of the returned array is determined by the Type Promotion Rules. + +Limitations +----------- +Keyword argument `kwargs` is currently unsupported. +Otherwise ``NotImplementedError`` exception will be raised. + +See Also +-------- +:obj:`dpnp.round` : Evenly round to the given number of decimals. +:obj:`dpnp.ceil` : Compute the ceiling of the input, element-wise. +:obj:`dpnp.floor` : Return the floor of the input, element-wise. +:obj:`dpnp.trunc` : Return the truncated value of the input, element-wise. + +Examples +-------- +>>> import dpnp as np +>>> 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.]) +""" - >>> np.signbit(np.array([1, -2.3, 2.1])) - array([False, True, False]) - """ +rint = DPNPUnaryFunc( + "rint", + ti._round_result_type, + ti._round, + _RINT_DOCSTRING, + mkl_fn_to_call=vmi._mkl_round_to_call, + mkl_impl_fn=vmi._round, +) - return check_nd_call_func( - numpy.signbit, - dpnp_signbit, - x, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) +_ROUND_DOCSTRING = """ +Rounds each element `x_i` of the input array `x` to +the nearest integer-valued number. + +For full documentation refer to :obj:`numpy.round`. + +Parameters +---------- +x : {dpnp.ndarray, usm_ndarray} + Input array, expected to have 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. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. + +Returns +------- +out : dpnp.ndarray + An array containing the element-wise rounded value. The data type + of the returned array is determined by the Type Promotion Rules. + +See Also +-------- +:obj:`dpnp.around` : Equivalent function; see for details. +:obj:`dpnp.ndarray.round` : Equivalent function. +:obj:`dpnp.rint` : Round elements of the array to the nearest integer. +:obj:`dpnp.ceil` : Compute the ceiling of the input, element-wise. +:obj:`dpnp.floor` : Return the floor of the input, element-wise. +:obj:`dpnp.trunc` : Return the truncated value of the input, element-wise. + +Examples +-------- +>>> import dpnp as np +>>> np.round(np.array([0.37, 1.64])) +array([0., 2.]) +>>> np.round(np.array([0.37, 1.64]), decimals=1) +array([0.4, 1.6]) +>>> np.round(np.array([.5, 1.5, 2.5, 3.5, 4.5])) # rounds to nearest even value +array([0., 2., 2., 4., 4.]) +>>> np.round(np.array([1, 2, 3, 11]), decimals=1) # ndarray of ints is returned +array([ 1, 2, 3, 11]) +>>> np.round(np.array([1, 2, 3, 11]), decimals=-1) +array([ 0, 0, 0, 10]) +""" -def subtract( - x1, - x2, - /, - out=None, - *, - where=True, - order="K", - dtype=None, - subok=True, - **kwargs, -): - """ - Subtract arguments, element-wise. +round = DPNPRound( + "round", + ti._round_result_type, + ti._round, + _ROUND_DOCSTRING, + mkl_fn_to_call=vmi._mkl_round_to_call, + mkl_impl_fn=vmi._round, +) - For full documentation refer to :obj:`numpy.subtract`. - Returns - ------- - out : dpnp.ndarray - The difference of `x1` and `x2`, element-wise. +_SIGN_DOCSTRING = """ +Computes an indication of the sign of each element `x_i` of input array `x` +using the signum function. + +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`. + +For full documentation refer to :obj:`numpy.sign`. + +Parameters +---------- +x : {dpnp.ndarray, usm_ndarray} + Input array, expected to have numeric data type. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +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. + +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 +-------- +:obj:`dpnp.signbit` : Returns element-wise `True` where signbit is set (less than zero). + +Examples +-------- +>>> import dpnp as np +>>> np.sign(np.array([-5., 4.5])) +array([-1.0, 1.0]) +>>> np.sign(np.array(0)) +array(0) +>>> np.sign(np.array(5-2j)) +array([1+0j]) +""" - Limitations - ----------- - Parameters `x1` and `x2` are supported as either scalar, :class:`dpnp.ndarray` - or :class:`dpctl.tensor.usm_ndarray`, but both `x1` and `x2` can not be scalars at the same time. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Keyword argument `kwargs` is currently unsupported. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. +sign = DPNPUnaryFunc( + "sign", + ti._sign_result_type, + ti._sign, + _SIGN_DOCSTRING, + acceptance_fn=acceptance_fn_sign, +) - Notes - ----- - Equivalent to `x1` - `x2` in terms of array broadcasting. - Examples - -------- - >>> import dpnp as np - >>> np.subtract(dp.array([4, 3]), np.array([2, 7])) - array([ 2, -4]) - - >>> x1 = np.arange(9.0).reshape((3, 3)) - >>> x2 = np.arange(3.0) - >>> np.subtract(x1, x2) - array([[ 0., 0., 0.], - [ 3., 3., 3.], - [ 6., 6., 6.]]) - - The ``-`` operator can be used as a shorthand for ``subtract`` on - :class:`dpnp.ndarray`. - - >>> x1 - x2 - array([[ 0., 0., 0.], - [ 3., 3., 3.], - [ 6., 6., 6.]]) - """ +_SIGNBIT_DOCSTRING = """ +Computes an indication of whether the sign bit of each element `x_i` of +input array `x` is set. + +For full documentation refer to :obj:`numpy.signbit`. + +Parameters +---------- +x : {dpnp.ndarray, usm_ndarray} + Input array, expected to have numeric data type. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +Returns +------- +out : dpnp.ndarray + An array containing the element-wise results. The returned array + must have a data type of `bool`. + +Limitations +----------- +Parameters `where` nd `subok` are supported with their default values. +Keyword argument `kwargs` is currently unsupported. +Otherwise ``NotImplementedError`` exception will be raised. + +See Also +-------- +:obj:`dpnp.sign` : Returns an element-wise indication of the sign of a number. + +Examples +-------- +>>> import dpnp as np +>>> np.signbit(np.array([-1.2])) +array([True]) + +>>> np.signbit(np.array([1, -2.3, 2.1])) +array([False, True, False]) +""" - return check_nd_call_func( - numpy.subtract, - dpnp_subtract, - x1, - x2, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) +signbit = DPNPUnaryFunc( + "signbit", + ti._signbit_result_type, + ti._signbit, + _SIGNBIT_DOCSTRING, +) + + +_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`. + +For full documentation refer to :obj:`numpy.subtract`. + +Parameters +---------- +x1 : {dpnp.ndarray, usm_ndarray} + First input array, expected to have numeric data type. +x2 : {dpnp.ndarray, usm_ndarray} + Second input array, also expected to have numeric data type. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +Returns +------- +out : dpnp.ndarray + an array containing the result of element-wise subtraction. The data type + of the returned array is determined by the Type Promotion Rules. + +Limitations +----------- +Parameters `where` and `subok` are supported with their default values. +Keyword argument `kwargs` is currently unsupported. +Otherwise ``NotImplementedError`` exception will be raised. + +Notes +----- +Equivalent to `x1` - `x2` in terms of array broadcasting. + +Examples +-------- +>>> import dpnp as np +>>> np.subtract(dp.array([4, 3]), np.array([2, 7])) +array([ 2, -4]) + +>>> x1 = np.arange(9.0).reshape((3, 3)) +>>> x2 = np.arange(3.0) +>>> np.subtract(x1, x2) +array([[ 0., 0., 0.], + [ 3., 3., 3.], + [ 6., 6., 6.]]) + +The ``-`` operator can be used as a shorthand for ``subtract`` on +:class:`dpnp.ndarray`. + +>>> x1 - x2 +array([[ 0., 0., 0.], + [ 3., 3., 3.], + [ 6., 6., 6.]]) +""" + +subtract = DPNPBinaryFunc( + "subtract", + ti._subtract_result_type, + ti._subtract, + _SUBTRACT_DOCSTRING, + mkl_fn_to_call=vmi._mkl_sub_to_call, + mkl_impl_fn=vmi._sub, + binary_inplace_fn=ti._subtract_inplace, + acceptance_fn=acceptance_fn_subtract, +) def sum( @@ -2888,14 +2793,16 @@ def sum( Limitations ----------- - Parameters `initial` and `where` are only supported with their default values. + Parameters `initial` and `where` are only supported with their default + values. Otherwise ``NotImplementedError`` exception will be raised. See Also -------- :obj:`dpnp.ndarray.sum` : Equivalent method. :obj:`dpnp.cumsum` : Cumulative sum of array elements. - :obj:`dpnp.trapz` : Integration of array values using the composite trapezoidal rule. + :obj:`dpnp.trapz` : Integration of array values using the composite + trapezoidal rule. :obj:`dpnp.mean` : Compute the arithmetic mean. :obj:`dpnp.average` : Compute the weighted average. @@ -2926,67 +2833,62 @@ def sum( raise NotImplementedError( "initial keyword argument is only supported with its default value." ) - elif where is not True: + if where is not True: raise NotImplementedError( "where keyword argument is only supported with its default value." ) - else: - if ( - len(a.shape) == 2 - and a.itemsize == 4 - and ( - ( - axis == (0,) - and a.flags.c_contiguous - and 32 <= a.shape[1] <= 1024 - and a.shape[0] > a.shape[1] - ) - or ( - axis == (1,) - and a.flags.f_contiguous - and 32 <= a.shape[0] <= 1024 - and a.shape[1] > a.shape[0] - ) - ) - ): - from dpnp.backend.extensions.sycl_ext import _sycl_ext_impl - - input = a - if axis == (1,): - input = input.T - input = dpnp.get_usm_ndarray(input) - - queue = input.sycl_queue - out_dtype = ( - dtu._default_accumulation_dtype(input.dtype, queue) - if dtype is None - else dtype - ) - output = dpt.empty( - input.shape[1], dtype=out_dtype, sycl_queue=queue - ) - get_sum = _sycl_ext_impl._get_sum_over_axis_0 - sum = get_sum(input, output) + sycl_sum_call = False + if len(a.shape) == 2 and a.itemsize == 4: + c_contiguous_rules = ( + axis == (0,) + and a.flags.c_contiguous + and 32 <= a.shape[1] <= 1024 + and a.shape[0] > a.shape[1] + ) + f_contiguous_rules = ( + axis == (1,) + and a.flags.f_contiguous + and 32 <= a.shape[0] <= 1024 + and a.shape[1] > a.shape[0] + ) + sycl_sum_call = c_contiguous_rules or f_contiguous_rules + + if sycl_sum_call: + input = a + if axis == (1,): + input = input.T + input = dpnp.get_usm_ndarray(input) + + queue = input.sycl_queue + out_dtype = ( + dtu._default_accumulation_dtype(input.dtype, queue) + if dtype is None + else dtype + ) + output = dpt.empty(input.shape[1], dtype=out_dtype, sycl_queue=queue) + + get_sum = _sycl_ext_impl._get_sum_over_axis_0 + sycl_sum = get_sum(input, output) - if sum: - sum(input, output, []).wait() - result = dpnp_array._create_from_usm_ndarray(output) + if sycl_sum: + sycl_sum(input, output, []).wait() + result = dpnp_array._create_from_usm_ndarray(output) - if keepdims: - if axis == (0,): - res_sh = (1,) + output.shape - else: - res_sh = output.shape + (1,) - result = result.reshape(res_sh) + if keepdims: + if axis == (0,): + res_sh = (1,) + output.shape + else: + res_sh = output.shape + (1,) + result = result.reshape(res_sh) - return result + return result - y = dpt.sum( - dpnp.get_usm_ndarray(a), axis=axis, dtype=dtype, keepdims=keepdims - ) - result = dpnp_array._create_from_usm_ndarray(y) - return dpnp.get_result_array(result, out, casting="same_kind") + y = dpt.sum( + dpnp.get_usm_ndarray(a), axis=axis, dtype=dtype, keepdims=keepdims + ) + result = dpnp_array._create_from_usm_ndarray(y) + return dpnp.get_result_array(result, out, casting="same_kind") def trapz(y1, x1=None, dx=1.0, axis=-1): @@ -3052,57 +2954,55 @@ def trapz(y1, x1=None, dx=1.0, axis=-1): true_divide = divide -def trunc( - x, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Compute the truncated value of the input, element-wise. - - For full documentation refer to :obj:`numpy.trunc`. - - Returns - ------- - out : dpnp.ndarray - The truncated value of each element of `x`. - - Limitations - ----------- - Parameter `x` is only supported as either :class:`dpnp.ndarray` or :class:`dpctl.tensor.usm_ndarray`. - Parameters `where`, `dtype`, and `subok` are supported with their default values. - Keyword argument `kwargs` is currently unsupported. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by real-value data types. - - See Also - -------- - :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. - - Examples - -------- - >>> import dpnp as np - >>> 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_DOCSTRING = """ +trunc(x, out=None, order='K') + +Returns the truncated value for each element `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 +signed number `x` is discarded. + +Parameters +---------- +x : {dpnp.ndarray, usm_ndarray} + Input array, expected to have a real-valued data type. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +Returns +------- +out : dpnp.ndarray + An array containing the truncated value of each element in `x`. The data type + of the returned array is determined by the Type Promotion Rules. + +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 +-------- +: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. + +Examples +-------- +>>> import dpnp as np +>>> 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]) +""" - return check_nd_call_func( - numpy.trunc, - dpnp_trunc, - x, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) +trunc = DPNPUnaryFunc( + "trunc", + ti._trunc_result_type, + ti._trunc, + _TRUNC_DOCSTRING, + mkl_fn_to_call=vmi._mkl_trunc_to_call, + mkl_impl_fn=vmi._trunc, +) diff --git a/dpnp/dpnp_iface_trigonometric.py b/dpnp/dpnp_iface_trigonometric.py index c29bd7218a81..38e6bf3c07a1 100644 --- a/dpnp/dpnp_iface_trigonometric.py +++ b/dpnp/dpnp_iface_trigonometric.py @@ -37,45 +37,26 @@ """ +# pylint: disable=protected-access +# pylint: disable=c-extension-no-member +# pylint: disable=duplicate-code +# pylint: disable=no-name-in-module + import dpctl.tensor as dpt +import dpctl.tensor._tensor_elementwise_impl as ti import numpy import dpnp -from dpnp.dpnp_algo import * -from dpnp.dpnp_array import dpnp_array -from dpnp.dpnp_utils import * - -from .dpnp_algo.dpnp_elementwise_common import ( - check_nd_call_func, - dpnp_acos, - dpnp_acosh, - dpnp_asin, - dpnp_asinh, - dpnp_atan, - dpnp_atan2, - dpnp_atanh, - dpnp_cbrt, - dpnp_cos, - dpnp_cosh, - dpnp_exp, - dpnp_exp2, - dpnp_expm1, - dpnp_hypot, - dpnp_log, - dpnp_log1p, - dpnp_log2, - dpnp_log10, - dpnp_logaddexp, - dpnp_reciprocal, - dpnp_rsqrt, - dpnp_sin, - dpnp_sinh, - dpnp_sqrt, - dpnp_square, - dpnp_tan, - dpnp_tanh, +import dpnp.backend.extensions.vm._vm_impl as vmi +from dpnp.dpnp_algo import ( + dpnp_degrees, + dpnp_radians, + dpnp_unwrap, ) +from dpnp.dpnp_algo.dpnp_elementwise_common import DPNPBinaryFunc, DPNPUnaryFunc +from dpnp.dpnp_array import dpnp_array +from dpnp.dpnp_utils import call_origin __all__ = [ "arccos", @@ -115,609 +96,561 @@ ] -def arccos( - x, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Trigonometric inverse cosine, element-wise. - - For full documentation refer to :obj:`numpy.arccos`. - - Returns - ------- - out : dpnp.ndarray - The inverse cosine of each element of `x`. - - Limitations - ----------- - Parameter `x` is only supported as either :class:`dpnp.ndarray` or :class:`dpctl.tensor.usm_ndarray`. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Keyword argument `kwargs` is currently unsupported. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. - - 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. - - Examples - -------- - >>> import dpnp as np - >>> x = np.array([1, -1]) - >>> np.arccos(x) - array([0.0, 3.14159265]) - - """ - - return check_nd_call_func( - numpy.arccos, - dpnp_acos, - x, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) - - -def arccosh( - x, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Inverse hyperbolic cosine, element-wise. - - For full documentation refer to :obj:`numpy.arccosh`. - - Returns - ------- - out : dpnp.ndarray - The hyperbolic inverse cosine of each element of `x`. - - Limitations - ----------- - Parameter `x` is only supported as either :class:`dpnp.ndarray` or :class:`dpctl.tensor.usm_ndarray`. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Keyword argument `kwargs` is currently unsupported. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. - - See Also - -------- - :obj:`dpnp.cosh` : Hyperbolic cosine, element-wise. - :obj:`dpnp.arctanh` : Hyperbolic inverse tangent, element-wise. - :obj:`dpnp.arcsinh` : Hyperbolic inverse sine, element-wise. - :obj:`dpnp.arccos` : Trigonometric inverse cosine, element-wise. - - Examples - -------- - >>> import dpnp as np - >>> x = np.array([1.0, np.e, 10.0]) - >>> np.arccosh(x) - array([0.0, 1.65745445, 2.99322285]) - - """ - - return check_nd_call_func( - numpy.arccosh, - dpnp_acosh, - x, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) - - -def arcsin( - x, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Inverse sine, element-wise. - - For full documentation refer to :obj:`numpy.arcsin`. - - Returns - ------- - out : dpnp.ndarray - The inverse sine of each element of `x`. - - Limitations - ----------- - Parameter `x` is only supported as either :class:`dpnp.ndarray` or :class:`dpctl.tensor.usm_ndarray`. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Keyword argument `kwargs` is currently unsupported. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. - - See Also - -------- - :obj:`dpnp.sin` : Trigonometric sine, element-wise. - :obj:`dpnp.arctan` : Trigonometric inverse tangent, element-wise. - :obj:`dpnp.arccos` : Trigonometric inverse cosine, element-wise. - :obj:`dpnp.arcsinh` : Hyperbolic inverse sine, element-wise. - - Examples - -------- - >>> import dpnp as np - >>> x = np.array([0, 1, -1]) - >>> np.arcsin(x) - array([0.0, 1.5707963267948966, -1.5707963267948966]) - - """ - - return check_nd_call_func( - numpy.arcsin, - dpnp_asin, - x, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) - - -def arcsinh( - x, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Inverse hyperbolic sine, element-wise. - - For full documentation refer to :obj:`numpy.arcsinh`. - - Returns - ------- - out : dpnp.ndarray - The hyperbolic inverse sine of each element of `x`. - - Limitations - ----------- - Parameter `x` is only supported as either :class:`dpnp.ndarray` or :class:`dpctl.tensor.usm_ndarray`. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Keyword argument `kwargs` is currently unsupported. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. - - 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. - - Examples - -------- - >>> import dpnp as np - >>> x = np.array([np.e, 10.0]) - >>> np.arcsinh(x) - array([1.72538256, 2.99822295]) - - """ - - return check_nd_call_func( - numpy.arcsinh, - dpnp_asinh, - x, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) - - -def arctan( - x, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Trigonometric inverse tangent, element-wise. - - For full documentation refer to :obj:`numpy.arctan`. - - Returns - ------- - out : dpnp.ndarray - The inverse tangent of each element of `x`. - - Limitations - ----------- - Parameter `x` is only supported as either :class:`dpnp.ndarray` or :class:`dpctl.tensor.usm_ndarray`. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Keyword argument `kwargs` is currently unsupported. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported real-valued floating-point data type. - - See Also - -------- - :obj:`dpnp.arctan2` : 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. - - Examples - -------- - >>> import dpnp as np - >>> x = np.array([0, 1]) - >>> np.arctan(x) - array([0.0, 0.78539816]) - - """ - - return check_nd_call_func( - numpy.arctan, - dpnp_atan, - x, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) - - -def arctan2( - x1, - x2, - /, - out=None, - *, - where=True, - order="K", - dtype=None, - subok=True, - **kwargs, -): - """ - Element-wise arc tangent of `x1/x2` choosing the quadrant correctly. - - For full documentation refer to :obj:`numpy.arctan2`. - - Returns - ------- - out : dpnp.ndarray - The inverse tangent of `x1/x2`, element-wise. - - Limitations - ----------- - Parameters `x1` and `x2` are supported as either scalar, :class:`dpnp.ndarray` - or :class:`dpctl.tensor.usm_ndarray`, but both `x1` and `x2` can not be scalars at the same time. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Keyword arguments `kwargs` are currently unsupported. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by real-valued data types. - - See Also - -------- - :obj:`dpnp.arctan` : 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. - - Examples - -------- - >>> import dpnp as np - >>> x1 = np.array([1., -1.]) - >>> x2 = np.array([0., 0.]) - >>> np.arctan2(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) - 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 - array([-135., -45., 45., 135.]) - - """ - - return check_nd_call_func( - numpy.arctan2, - dpnp_atan2, - x1, - x2, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) - - -def arctanh( - x, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Hyperbolic inverse tangent, element-wise. - - For full documentation refer to :obj:`numpy.arctanh`. - - Returns - ------- - out : dpnp.ndarray - The hyperbolic inverse tangent of each element of `x`. - - Limitations - ----------- - Parameter `x` is only supported as either :class:`dpnp.ndarray` or :class:`dpctl.tensor.usm_ndarray`. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Keyword argument `kwargs` is currently unsupported. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. - - 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. - - Examples - -------- - >>> import dpnp as np - >>> x = np.array([0, -0.5]) - >>> np.arctanh(x) - array([0.0, -0.54930614]) - - """ - - return check_nd_call_func( - numpy.arctanh, - dpnp_atanh, - x, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) +_ACOS_DOCSTRING = """ +Computes inverse cosine for each element `x_i` for input array `x`. + +For full documentation refer to :obj:`numpy.arccos`. + +Parameters +---------- +x : {dpnp.ndarray, usm_ndarray} + Input array, expected to have numeric data type. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +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. + +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 +-------- +: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. + +Examples +-------- +>>> import dpnp as np +>>> x = np.array([1, -1]) +>>> np.arccos(x) +array([0.0, 3.14159265]) +""" +arccos = DPNPUnaryFunc( + "arccos", + ti._acos_result_type, + ti._acos, + _ACOS_DOCSTRING, + mkl_fn_to_call=vmi._mkl_acos_to_call, + mkl_impl_fn=vmi._acos, +) -def cbrt( - x, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Return the cube-root of an array, element-wise. - For full documentation refer to :obj:`numpy.cbrt`. +_ACOSH_DOCSTRING = """ +Computes hyperbolic inverse cosine for each element `x_i` for input array `x`. + +For full documentation refer to :obj:`numpy.arccosh`. + +Parameters +---------- +x : {dpnp.ndarray, usm_ndarray} + Input array, expected to have numeric data type. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +Returns +------- +out : dpnp.ndarray + An array containing the element-wise inverse hyperbolic cosine. + The data type of the returned array is determined by + the Type Promotion Rules. + +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 +-------- +:obj:`dpnp.cosh` : Hyperbolic cosine, element-wise. +:obj:`dpnp.arctanh` : Hyperbolic inverse tangent, element-wise. +:obj:`dpnp.arcsinh` : Hyperbolic inverse sine, element-wise. +:obj:`dpnp.arccos` : Trigonometric inverse cosine, element-wise. + +Examples +-------- +>>> import dpnp as np +>>> x = np.array([1.0, np.e, 10.0]) +>>> np.arccosh(x) +array([0.0, 1.65745445, 2.99322285]) +""" - Parameters - ---------- - x : {dpnp.ndarray, usm_ndarray} - Input array, must 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. - order : {"C", "F", "A", "K"}, optional - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". +arccosh = DPNPUnaryFunc( + "arccosh", + ti._acosh_result_type, + ti._acosh, + _ACOSH_DOCSTRING, + mkl_fn_to_call=vmi._mkl_acosh_to_call, + mkl_impl_fn=vmi._acosh, +) - Returns - ------- - out : dpnp.ndarray - The cube-root of each element in `x`. - Limitations - ----------- - Parameters `where`, `dtype` and `subok` are supported with their default values. - Keyword argument `kwargs` is currently unsupported. - Otherwise the function will be executed sequentially on CPU. +_ASIN_DOCSTRING = """ +Computes inverse sine for each element `x_i` for input array `x`. + +For full documentation refer to :obj:`numpy.arcsin`. + +Parameters +---------- +x : {dpnp.ndarray, usm_ndarray} + Input array, expected to have numeric data type. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +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. + +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 +-------- +:obj:`dpnp.sin` : Trigonometric sine, element-wise. +:obj:`dpnp.arctan` : Trigonometric inverse tangent, element-wise. +:obj:`dpnp.arccos` : Trigonometric inverse cosine, element-wise. +:obj:`dpnp.arcsinh` : Hyperbolic inverse sine, element-wise. + +Examples +-------- +>>> import dpnp as np +>>> x = np.array([0, 1, -1]) +>>> np.arcsin(x) +array([0.0, 1.5707963267948966, -1.5707963267948966]) +""" - See Also - -------- - :obj:`dpnp.sqrt` : Return the positive square-root of an array, element-wise. +arcsin = DPNPUnaryFunc( + "arcsin", + ti._asin_result_type, + ti._asin, + _ASIN_DOCSTRING, + mkl_fn_to_call=vmi._mkl_asin_to_call, + mkl_impl_fn=vmi._asin, +) - Examples - -------- - >>> import dpnp as np - >>> x = np.array([1, 8, 27]) - >>> np.cbrt(x) - array([1., 2., 3.]) - """ +_ASINH_DOCSTRING = """ +Computes inverse hyperbolic sine for each element `x_i` for input array `x`. + +For full documentation refer to :obj:`numpy.arcsinh`. + +Parameters +---------- +x : {dpnp.ndarray, usm_ndarray} + Input array, expected to have numeric data type. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type.. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +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. + +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 +-------- +: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. + +Examples +-------- +>>> import dpnp as np +>>> x = np.array([np.e, 10.0]) +>>> np.arcsinh(x) +array([1.72538256, 2.99822295]) +""" - return check_nd_call_func( - numpy.cbrt, - dpnp_cbrt, - x, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) +arcsinh = DPNPUnaryFunc( + "arcsinh", + ti._asinh_result_type, + ti._asinh, + _ASINH_DOCSTRING, + mkl_fn_to_call=vmi._mkl_asinh_to_call, + mkl_impl_fn=vmi._asinh, +) -def cos( - x, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Trigonometric cosine, element-wise. +_ATAN_DOCSTRING = """ +Computes inverse tangent for each element `x_i` for input array `x`. + +For full documentation refer to :obj:`numpy.arctan`. + +Parameters +---------- +x : {dpnp.ndarray, usm_ndarray} + Input array, expected to have numeric data type. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type.. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +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. + +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 +-------- +:obj:`dpnp.arctan2` : 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. + +Examples +-------- +>>> import dpnp as np +>>> x = np.array([0, 1]) +>>> np.arctan(x) +array([0.0, 0.78539816]) +""" - For full documentation refer to :obj:`numpy.cos`. +arctan = DPNPUnaryFunc( + "arctan", + ti._atan_result_type, + ti._atan, + _ATAN_DOCSTRING, + mkl_fn_to_call=vmi._mkl_atan_to_call, + mkl_impl_fn=vmi._atan, +) - Returns - ------- - out : dpnp.ndarray - The cosine of each element of `x`. - Limitations - ----------- - Parameter `x` is only supported as either :class:`dpnp.ndarray` or :class:`dpctl.tensor.usm_ndarray`. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Keyword argument `kwargs` is currently unsupported. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. - - See Also - -------- - :obj:`dpnp.arccos` : 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. +_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. + +For full documentation refer to :obj:`numpy.arctan2`. + +Parameters +---------- +x1 : {dpnp.ndarray, usm_ndarray} + First input array, expected to have a real-valued floating-point + data type. +x2 : {dpnp.ndarray, usm_ndarray} + Second input array, also expected to have a real-valued + floating-point data type. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +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. + +Limitations +----------- +Parameters `where` and `subok` are supported with their default values. +Keyword arguments `kwargs` are currently unsupported. +Otherwise ``NotImplementedError`` exception will be raised. + +See Also +-------- +:obj:`dpnp.arctan` : 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. + +Examples +-------- +>>> import dpnp as np +>>> x1 = np.array([1., -1.]) +>>> x2 = np.array([0., 0.]) +>>> np.arctan2(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) +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 +array([-135., -45., 45., 135.]) +""" - Examples - -------- - >>> import dpnp as np - >>> x = np.array([0, np.pi/2, np.pi]) - >>> np.cos(x) - array([ 1.000000e+00, -4.371139e-08, -1.000000e+00]) +arctan2 = DPNPBinaryFunc( + "arctan2", + ti._atan2_result_type, + ti._atan2, + _ATAN2_DOCSTRING, + mkl_fn_to_call=vmi._mkl_atan2_to_call, + mkl_impl_fn=vmi._atan2, +) - """ - return check_nd_call_func( - numpy.cos, - dpnp_cos, - x, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) +_ATANH_DOCSTRING = """ +Computes hyperbolic inverse tangent for each element `x_i` for input array `x`. + +For full documentation refer to :obj:`numpy.arctanh`. + +Parameters +---------- +x : {dpnp.ndarray, usm_ndarray} + Input array, expected to have numeric data type. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +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. + +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 +-------- +: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. + +Examples +-------- +>>> import dpnp as np +>>> x = np.array([0, -0.5]) +>>> np.arctanh(x) +array([0.0, -0.54930614]) +""" +arctanh = DPNPUnaryFunc( + "arctanh", + ti._atanh_result_type, + ti._atanh, + _ATANH_DOCSTRING, + mkl_fn_to_call=vmi._mkl_atanh_to_call, + mkl_impl_fn=vmi._atanh, +) -def cosh( - x, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Hyperbolic cosine, element-wise. - For full documentation refer to :obj:`numpy.cosh`. +_CBRT_DOCSTRING = """ +Returns the cbrting for each element `x_i` for input array `x`. +The cbrt of the scalar `x` is the smallest integer `i`, such that `i >= 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. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +Returns +------- +out : dpnp.ndarray + An array containing the element-wise cbrting of input array. + The returned array has the same data type as `x`. + +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 +-------- +:obj:`dpnp.sqrt` : Return the positive square-root of an array, element-wise. + +Examples +-------- +>>> import dpnp as np +>>> x = np.array([1, 8, 27]) +>>> np.cbrt(x) +array([1., 2., 3.]) +""" - Returns - ------- - out : dpnp.ndarray - The hyperbolic cosine of each element of `x`. +cbrt = DPNPUnaryFunc( + "cbrt", + ti._cbrt_result_type, + ti._cbrt, + _CBRT_DOCSTRING, + mkl_fn_to_call=vmi._mkl_cbrt_to_call, + mkl_impl_fn=vmi._cbrt, +) - Limitations - ----------- - Parameter `x` is only supported as either :class:`dpnp.ndarray` or :class:`dpctl.tensor.usm_ndarray`. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Keyword argument `kwargs` is currently unsupported. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. - See Also - -------- - :obj:`dpnp.arccosh` : 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. +_COS_DOCSTRING = """ +Computes cosine for each element `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. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +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. + +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 +-------- +:obj:`dpnp.arccos` : 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. + +Examples +-------- +>>> import dpnp as np +>>> x = np.array([0, np.pi/2, np.pi]) +>>> np.cos(x) +array([ 1.000000e+00, -4.371139e-08, -1.000000e+00]) +""" +cos = DPNPUnaryFunc( + "cos", + ti._cos_result_type, + ti._cos, + _COS_DOCSTRING, + mkl_fn_to_call=vmi._mkl_cos_to_call, + mkl_impl_fn=vmi._cos, +) - Examples - -------- - >>> import dpnp as np - >>> x = np.array([0, np.pi/2, np.pi]) - >>> np.cosh(x) - array([1.0, 2.5091786, 11.591953]) - """ +_COSH_DOCSTRING = """ +Computes hyperbolic cosine for each element `x_i` for input array `x`. + +For full documentation refer to :obj:`numpy.cosh`. + +Parameters +---------- +x : {dpnp.ndarray, usm_ndarray} + Input array, expected to have numeric data type. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +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. + +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 +-------- +:obj:`dpnp.arccosh` : 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. + + +Examples +-------- +>>> import dpnp as np +>>> x = np.array([0, np.pi/2, np.pi]) +>>> np.cosh(x) +array([1.0, 2.5091786, 11.591953]) +""" - return check_nd_call_func( - numpy.cosh, - dpnp_cosh, - x, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) +cosh = DPNPUnaryFunc( + "cosh", + ti._cosh_result_type, + ti._cosh, + _COSH_DOCSTRING, + mkl_fn_to_call=vmi._mkl_cosh_to_call, + mkl_impl_fn=vmi._cosh, +) def deg2rad(x1): @@ -740,7 +673,7 @@ def deg2rad(x1): return radians(x1) -def degrees(x1): +def degrees(x1, **kwargs): """ Convert angles from radians to degrees. @@ -766,578 +699,536 @@ def degrees(x1): x1_desc = dpnp.get_dpnp_descriptor( x1, copy_when_strides=False, copy_when_nondefault_queue=False ) - if x1_desc: + if kwargs: + pass + elif x1_desc: return dpnp_degrees(x1_desc).get_pyobj() return call_origin(numpy.degrees, x1, **kwargs) -def exp( - x, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Calculate the exponential, element-wise. - - For full documentation refer to :obj:`numpy.exp`. - - Returns - ------- - out : dpnp.ndarray - The exponential of `x`, element-wise. - - Limitations - ----------- - Parameter `x` is only supported as either :class:`dpnp.ndarray` or :class:`dpctl.tensor.usm_ndarray`. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Keyword argument `kwargs` is currently unsupported. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. - - 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. - - Examples - -------- - >>> import dpnp as np - >>> x = np.arange(3.) - >>> np.exp(x) - array([1.0, 2.718281828, 7.389056099]) - - """ - - return check_nd_call_func( - numpy.exp, - dpnp_exp, - x, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) - - -def exp2( - x, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Calculate `2**p` for all `p` in the input array. - - For full documentation refer to :obj:`numpy.exp2`. - - Parameters - ---------- - x : {dpnp.ndarray, usm_ndarray} - Input array. - out : ({None, dpnp.ndarray, usm_ndarray}, optional): - Output array to populate. - Array must have the correct shape and the expected data type. - order : {"C", "F", "A", "K"}, optional - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". - - Returns - ------- - out : dpnp.ndarray - Element-wise 2 to the power `x`. - - Limitations - ----------- - Parameters `where`, `dtype` and `subok` are supported with their default values. - Keyword argument `kwargs` is currently unsupported. - Otherwise the function will be executed sequentially on CPU. - - See Also - -------- - :obj:`dpnp.exp` : Calculate exponential 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. - - Examples - -------- - >>> import dpnp as np - >>> x = np.arange(3.) - >>> np.exp2(x) - array([1., 2., 4.]) - - """ - - return check_nd_call_func( - numpy.exp2, - dpnp_exp2, - x, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) - - -def expm1( - x, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Return the exponential of the input array minus one, element-wise. - - For full documentation refer to :obj:`numpy.expm1`. - - Returns - ------- - out : dpnp.ndarray - The exponential of `x` minus one, element-wise. - - Limitations - ----------- - Parameter `x` is only supported as either :class:`dpnp.ndarray` or :class:`dpctl.tensor.usm_ndarray`. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Keyword argument `kwargs` is currently unsupported. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. - - See Also - -------- - :obj:`dpnp.exp` : Calculate exponential for all elements in the array. - :obj:`dpnp.exp2` : Calculate `2**x` for all elements in the array. - :obj:`dpnp.log1p` : Callculate ``log(1 + x)``, the inverse of expm1. - - Examples - -------- - >>> import dpnp as np - >>> x = np.arange(3.) - >>> np.expm1(x) - array([0.0, 1.718281828, 6.389056099]) - - >>> np.expm1(np.array(1e-10)) - array(1.00000000005e-10) - - >>> np.exp(np.array(1e-10)) - 1 - array(1.000000082740371e-10) - - """ - - return check_nd_call_func( - numpy.expm1, - dpnp_expm1, - x, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) - - -def hypot( - x1, - x2, - /, - out=None, - *, - where=True, - order="K", - dtype=None, - subok=True, - **kwargs, -): - """ - Given the "legs" of a right triangle, return its hypotenuse. - - For full documentation refer to :obj:`numpy.hypot`. - - Returns - ------- - out : dpnp.ndarray - The hypotenuse of the triangle(s). - - Limitations - ----------- - Parameters `x1` and `x2` are supported as either scalar, :class:`dpnp.ndarray` - or :class:`dpctl.tensor.usm_ndarray`, but both `x1` and `x2` can not be scalars at the same time. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Keyword argument `kwargs` is currently unsupported. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported real-valued data types. - - See Also - -------- - :obj:`dpnp.reduce_hypot` : The square root of the sum of squares of elements in the input array. - - Examples - -------- - >>> import dpnp as np - >>> x1 = 3 * np.ones((3, 3)) - >>> x2 = 4 * np.ones((3, 3)) - >>> np.hypot(x1, x2) - array([[5., 5., 5.], - [5., 5., 5.], - [5., 5., 5.]]) - - Example showing broadcast of scalar argument: - - >>> np.hypot(x1, 4) - array([[ 5., 5., 5.], - [ 5., 5., 5.], - [ 5., 5., 5.]]) - - """ - - return check_nd_call_func( - numpy.hypot, - dpnp_hypot, - x1, - x2, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) - - -def log( - x, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Natural logarithm, element-wise. - - The natural logarithm `log` is the inverse of the exponential function, - so that `log(exp(x)) = x`. The natural logarithm is logarithm in base `e`. - - For full documentation refer to :obj:`numpy.log`. - - Returns - ------- - out : dpnp.ndarray - The natural logarithm of `x`, element-wise. - - Limitations - ----------- - Parameters `x` is only supported as either :class:`dpnp.ndarray` or :class:`dpctl.tensor.usm_ndarray`. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. - - 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. - - Examples - -------- - >>> import dpnp as np - >>> x = np.array([1, np.e, np.e**2, 0]) - >>> np.log(x) - array([ 0., 1., 2., -inf]) - - """ - - return check_nd_call_func( - numpy.log, - dpnp_log, - x, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) - - -def log10( - x, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Return the base 10 logarithm of the input array, element-wise. - - For full documentation refer to :obj:`numpy.log10`. - - Returns - ------- - out : dpnp.ndarray - The base 10 logarithm of `x`, element-wise. - - Limitations - ----------- - Parameter `x` is only supported as either :class:`dpnp.ndarray` or :class:`dpctl.tensor.usm_ndarray`. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Keyword argument `kwargs` is currently unsupported. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. - - 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. - - Examples - -------- - >>> import dpnp as np - >>> x = np.arange(3.) - >>> np.log10(x) - array([-inf, 0.0, 0.30102999566]) - - >>> np.log10(np.array([1e-15, -3.])) - array([-15., nan]) - - """ - - return check_nd_call_func( - numpy.log10, - dpnp_log10, - x, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) - - -def log1p( - x, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Return the natural logarithm of one plus the input array, element-wise. - - For full documentation refer to :obj:`numpy.log1p`. - - Returns - ------- - out : dpnp.ndarray - The natural logarithm of `1+x`, element-wise. - - Limitations - ----------- - Parameter `x` is only supported as either :class:`dpnp.ndarray` or :class:`dpctl.tensor.usm_ndarray`. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Keyword argument `kwargs` is currently unsupported. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. - - 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. +_EXP_DOCSTRING = """ +Computes the exponential for each element `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. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +Returns +------- +out : dpnp.ndarray + An array containing the element-wise exponential of `x`. + The data type of the returned array is determined by + the Type Promotion Rules. + +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 +-------- +: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. + +Examples +-------- +>>> import dpnp as np +>>> x = np.arange(3.) +>>> np.exp(x) +array([1.0, 2.718281828, 7.389056099]) +""" - Examples - -------- - >>> import dpnp as np - >>> x = np.arange(3.) - >>> np.log1p(x) - array([0.0, 0.69314718, 1.09861229]) +exp = DPNPUnaryFunc( + "exp", + ti._exp_result_type, + ti._exp, + _EXP_DOCSTRING, + mkl_fn_to_call=vmi._mkl_exp_to_call, + mkl_impl_fn=vmi._exp, +) - >>> np.log1p(array(1e-99)) - array(1e-99) - >>> np.log(array(1 + 1e-99)) - array(0.0) +_EXP2_DOCSTRING = """ +Computes the base-2 exponential for each element `x_i` for input array `x`. + +For full documentation refer to :obj:`numpy.exp2`. + +Parameters +---------- +x : {dpnp.ndarray, usm_ndarray} + Input array, expected to have a floating-point data type. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +Returns +------- +out : dpnp.ndarray + An array containing the element-wise base-2 exponentials. + The data type of the returned array is determined by + the Type Promotion Rules. + +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 +-------- +:obj:`dpnp.exp` : Calculate exponential 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. + +Examples +-------- +>>> import dpnp as np +>>> x = np.arange(3.) +>>> np.exp2(x) +array([1., 2., 4.]) +""" - """ +exp2 = DPNPUnaryFunc( + "exp2", + ti._exp2_result_type, + ti._exp2, + _EXP2_DOCSTRING, + mkl_fn_to_call=vmi._mkl_exp2_to_call, + mkl_impl_fn=vmi._exp2, +) - return check_nd_call_func( - numpy.log1p, - dpnp_log1p, - x, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) +_EXPM1_DOCSTRING = """ +Computes the exponential 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`. + +For full documentation refer to :obj:`numpy.expm1`. + +Parameters +---------- +x : {dpnp.ndarray, usm_ndarray} + Input array, expected to have numeric data type. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +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. + +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 +-------- +:obj:`dpnp.exp` : Calculate exponential for all elements in the array. +:obj:`dpnp.exp2` : Calculate `2**x` for all elements in the array. +:obj:`dpnp.log1p` : Callculate ``log(1 + x)``, the inverse of expm1. + +Examples +-------- +>>> import dpnp as np +>>> x = np.arange(3.) +>>> np.expm1(x) +array([0.0, 1.718281828, 6.389056099]) + +>>> np.expm1(np.array(1e-10)) +array(1.00000000005e-10) + +>>> np.exp(np.array(1e-10)) - 1 +array(1.000000082740371e-10) +""" -def log2( - x, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Return the base 2 logarithm of the input array, element-wise. +expm1 = DPNPUnaryFunc( + "expm1", + ti._expm1_result_type, + ti._expm1, + _EXPM1_DOCSTRING, + mkl_fn_to_call=vmi._mkl_expm1_to_call, + mkl_impl_fn=vmi._expm1, +) - For full documentation refer to :obj:`numpy.log2`. - Returns - ------- - out : dpnp.ndarray - The base 2 logarithm of `x`, element-wise. +_HYPOT_DOCSTRING = """ +Calculates the hypotenuse for a right triangle with "legs" `x1_i` and `x2_i` of +input arrays `x1` and `x2`. + +For full documentation refer to :obj:`numpy.hypot`. + +Parameters +---------- +x1 : {dpnp.ndarray, usm_ndarray} + First input array, expected to have a real-valued data type. +x2 : {dpnp.ndarray, usm_ndarray} + Second input array, also expected to have a real-valued data type. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +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. + +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 +-------- +:obj:`dpnp.reduce_hypot` : The square root of the sum of squares of elements in the input array. + +Examples +-------- +>>> import dpnp as np +>>> x1 = 3 * np.ones((3, 3)) +>>> x2 = 4 * np.ones((3, 3)) +>>> np.hypot(x1, x2) +array([[5., 5., 5.], + [5., 5., 5.], + [5., 5., 5.]]) + +Example showing broadcast of scalar argument: + +>>> np.hypot(x1, 4) +array([[ 5., 5., 5.], + [ 5., 5., 5.], + [ 5., 5., 5.]]) +""" - Limitations - ----------- - Parameter `x` is only supported as either :class:`dpnp.ndarray` or :class:`dpctl.tensor.usm_ndarray`. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Keyword argument `kwargs` is currently unsupported. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. +hypot = DPNPBinaryFunc( + "hypot", + ti._hypot_result_type, + ti._hypot, + _HYPOT_DOCSTRING, + mkl_fn_to_call=vmi._mkl_hypot_to_call, + mkl_impl_fn=vmi._hypot, +) - 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. - Examples - -------- - >>> import dpnp as np - >>> x = np.array([0, 1, 2, 2**4]) - >>> np.log2(x) - array([-inf, 0.0, 1.0, 4.0]) +_LOG_DOCSTRING = """ +Computes the natural logarithm element-wise. + +For full documentation refer to :obj:`numpy.log`. + +Parameters +---------- +x : {dpnp.ndarray, usm_ndarray} + Input array, expected to have numeric data type. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +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. + +Limitations +----------- +Parameters `where` and `subok` are supported with their default values. +Otherwise ``NotImplementedError`` exception will be raised. + +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. + +Examples +-------- +>>> import dpnp as np +>>> x = np.array([1, np.e, np.e**2, 0]) +>>> np.log(x) +array([ 0., 1., 2., -inf]) +""" + +log = DPNPUnaryFunc( + "log", + ti._log_result_type, + ti._log, + _LOG_DOCSTRING, + mkl_fn_to_call=vmi._mkl_ln_to_call, + mkl_impl_fn=vmi._ln, +) - >>> 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]) - """ +_LOG10_DOCSTRING = """ +Computes the base-10 logarithm for each element `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. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +Returns +------- +out : dpnp.ndarray + An array containing the base-10 logarithm of `x`. + The data type of the returned array is determined by the + Type Promotion Rules. + +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 +-------- +: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. + +Examples +-------- +>>> import dpnp as np +>>> x = np.arange(3.) +>>> np.log10(x) +array([-inf, 0.0, 0.30102999566]) + +>>> np.log10(np.array([1e-15, -3.])) +array([-15., nan]) +""" - return check_nd_call_func( - numpy.log2, - dpnp_log2, - x, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) +log10 = DPNPUnaryFunc( + "log10", + ti._log10_result_type, + ti._log10, + _LOG10_DOCSTRING, + mkl_fn_to_call=vmi._mkl_log10_to_call, + mkl_impl_fn=vmi._log10, +) -def logaddexp( - x1, - x2, - /, - out=None, - *, - where=True, - order="K", - dtype=None, - subok=True, - **kwargs, -): - """ - Calculates ``log(exp(x1) + exp(x2))``, element-wise. +_LOG1P_DOCSTRING = """ +Computes an approximation of `log(1+x)` element-wise. + +For full documentation refer to :obj:`numpy.log1p`. + +Parameters +---------- +x : {dpnp.ndarray, usm_ndarray} + Input array, expected to have numeric data type. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +Returns +------- +out : dpnp.ndarray + An array containing the element-wise `log(1+x)` values. The data type + of the returned array is determined by the Type Promotion Rules. + +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 +-------- +: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. + +Examples +-------- +>>> import dpnp as np +>>> x = np.arange(3.) +>>> np.log1p(x) +array([0.0, 0.69314718, 1.09861229]) + +>>> np.log1p(array(1e-99)) +array(1e-99) + +>>> np.log(array(1 + 1e-99)) +array(0.0) +""" - For full documentation refer to :obj:`numpy.logaddexp`. +log1p = DPNPUnaryFunc( + "log1p", + ti._log1p_result_type, + ti._log1p, + _LOG1P_DOCSTRING, + mkl_fn_to_call=vmi._mkl_log1p_to_call, + mkl_impl_fn=vmi._log1p, +) - Returns - ------- - out : dpnp.ndarray - Logarithm of ``exp(x1) + exp(x2)``, element-wise. - Limitations - ----------- - Parameters `x1` and `x2` are supported as either scalar, :class:`dpnp.ndarray` - or :class:`dpctl.tensor.usm_ndarray`, but both `x1` and `x2` can not be scalars at the same time. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Keyword arguments `kwargs` are currently unsupported. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by real-valued data types. +_LOG2_DOCSTRING = """ +Computes the base-2 logarithm for each element `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. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +Returns +------- +out : dpnp.ndarray + An array containing the base-2 logarithm of `x`. + The data type of the returned array is determined by the + Type Promotion Rules. + +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 +-------- +: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. + +Examples +-------- +>>> import dpnp as np +>>> x = np.array([0, 1, 2, 2**4]) +>>> np.log2(x) +array([-inf, 0.0, 1.0, 4.0]) + +>>> 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]) +""" - See Also - -------- - :obj:`dpnp.log` : Natural logarithm, element-wise. - :obj:`dpnp.exp` : Exponential, element-wise. - :obj:`dpnp.logsumdexp` : Logarithm of the sum of exponentials of elements in the input array. +log2 = DPNPUnaryFunc( + "log2", + ti._log2_result_type, + ti._log2, + _LOG2_DOCSTRING, + mkl_fn_to_call=vmi._mkl_log2_to_call, + mkl_impl_fn=vmi._log2, +) - Examples - -------- - >>> import dpnp as np - >>> prob1 = np.log(np.array(1e-50)) - >>> prob2 = np.log(np.array(2.5e-50)) - >>> prob12 = np.logaddexp(prob1, prob2) - >>> prob12 - array(-113.87649168) - >>> np.exp(prob12) - array(3.5e-50) - """ +_LOGADDEXP_DOCSTRING = """ +Calculates the natural logarithm of the sum of exponentiations 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`. + +For full documentation refer to :obj:`numpy.logaddexp`. + +Parameters +---------- +x1 : {dpnp.ndarray, usm_ndarray} + First input array, expected to have a real-valued floating-point + data type. +x2 : {dpnp.ndarray, usm_ndarray} + Second input array, also expected to have a real-valued + floating-point data type. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +Returns +------- +out : dpnp.ndarray + An array containing the result of element-wise result. The data type + of the returned array is determined by the Type Promotion Rules. + +Limitations +----------- +Parameters `where` and `subok` are supported with their default values. +Keyword arguments `kwargs` are currently unsupported. +Otherwise ``NotImplementedError`` exception will be raised. + +See Also +-------- +:obj:`dpnp.log` : Natural logarithm, element-wise. +:obj:`dpnp.exp` : Exponential, element-wise. +:obj:`dpnp.logsumdexp` : Logarithm of the sum of exponentials of elements in the input array. + +Examples +-------- +>>> import dpnp as np +>>> prob1 = np.log(np.array(1e-50)) +>>> prob2 = np.log(np.array(2.5e-50)) +>>> prob12 = np.logaddexp(prob1, prob2) +>>> prob12 +array(-113.87649168) +>>> np.exp(prob12) +array(3.5e-50) +""" - return check_nd_call_func( - numpy.logaddexp, - dpnp_logaddexp, - x1, - x2, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) +logaddexp = DPNPBinaryFunc( + "logaddexp", + ti._logaddexp_result_type, + ti._logaddexp, + _LOGADDEXP_DOCSTRING, +) def logsumexp(x, axis=None, out=None, dtype=None, keepdims=False): """ - Calculates the logarithm of the sum of exponentials of elements in the input array. + Calculates the logarithm of the sum of exponentials of elements in + the input array. Parameters ---------- @@ -1383,7 +1274,8 @@ def logsumexp(x, axis=None, out=None, dtype=None, keepdims=False): -------- :obj:`dpnp.log` : Natural logarithm, element-wise. :obj:`dpnp.exp` : Exponential, element-wise. - :obj:`dpnp.logaddexp` : Logarithm of the sum of exponentiations of the inputs, element-wise. + :obj:`dpnp.logaddexp` : Logarithm of the sum of exponentiations of + the inputs, element-wise. Examples -------- @@ -1404,80 +1296,59 @@ def logsumexp(x, axis=None, out=None, dtype=None, keepdims=False): return dpnp.get_result_array(result, out, casting="same_kind") -def reciprocal( - x, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Return the reciprocal of the argument, element-wise. - - For full documentation refer to :obj:`numpy.reciprocal`. - - Parameters - ---------- - x : {dpnp.ndarray, usm_ndarray} - Input array. - out : {None, dpnp.ndarray, usm_ndarray}, optional - Output array to populate. - Array must have the correct shape and the expected data type. - order : {"C", "F", "A", "K"}, optional - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". - - Returns - ------- - out : dpnp.ndarray - An array containing the element-wise reciprocals. - - Notes - ----- - If `x` has a integral data type, the output will have the default - real-valued floating-point data type for the device where - input array `x` is allocated. If `x` has a floating-point - data type, the output will have the same data type. - - Limitations - ----------- - Parameters `where`, `dtype` and `subok` are supported with their default values. - Keyword argument `kwargs` is currently unsupported. - Otherwise the function will be executed sequentially on CPU. - - See Also - -------- - :obj:`dpnp.rsqrt` : Return the reciprocal square-root of an array, element-wise. - - Examples - -------- - >>> import dpnp as np - >>> x = np.array([1, 2., 3.33]) - >>> np.reciprocal(x) - array([1.0, 0.5, 0.3003003]) - - """ +_RECIPROCAL_DOCSTRING = """ +Computes the reciprocal of each element `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. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +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. + +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 +-------- +:obj:`dpnp.rsqrt` : Return the reciprocal square-root of an array, element-wise. + +Examples +-------- +>>> import dpnp as np +>>> x = np.array([1, 2., 3.33]) +>>> np.reciprocal(x) +array([1.0, 0.5, 0.3003003]) +""" - return check_nd_call_func( - numpy.reciprocal, - dpnp_reciprocal, - x, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) +reciprocal = DPNPUnaryFunc( + "reciprocal", + ti._reciprocal_result_type, + ti._reciprocal, + _RECIPROCAL_DOCSTRING, +) def reduce_hypot(x, axis=None, out=None, dtype=None, keepdims=False): """ - Calculates the square root of the sum of squares of elements in the input array. + Calculates the square root of the sum of squares of elements in + the input array. Parameters ---------- @@ -1521,7 +1392,8 @@ def reduce_hypot(x, axis=None, out=None, dtype=None, keepdims=False): See Also -------- - :obj:`dpnp.hypot` : Given the "legs" of a right triangle, return its hypotenuse. + :obj:`dpnp.hypot` : Given the "legs" of a right triangle, return its + hypotenuse. Examples -------- @@ -1542,67 +1414,50 @@ def reduce_hypot(x, axis=None, out=None, dtype=None, keepdims=False): return dpnp.get_result_array(result, out, casting="same_kind") -def rsqrt( - x, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Computes the reciprocal square-root for each element `x_i` for input array `x`. - - Parameters - ---------- - x : {dpnp.ndarray, usm_ndarray} - Input array, must 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. - order : {"C", "F", "A", "K"}, optional - Memory layout of the newly output array, if parameter `out` is ``None``. - Default: "K". - - Returns - ------- - out : dpnp.ndarray - The reciprocal square-root, element-wise. - - Limitations - ----------- - Parameters `where`, `dtype` and `subok` are supported with their default values. - Keyword argument `kwargs` is currently unsupported. - Otherwise the function will be executed sequentially on CPU. - - 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. - - Examples - -------- - >>> import dpnp as np - >>> x = np.array([1, 8, 27]) - >>> np.rsqrt(x) - array([1. , 0.35355338, 0.19245009]) - - """ +_RSQRT_DOCSTRING = """ +Computes the reciprocal square-root for each element `x_i` for input array `x`. + +Parameters +---------- +x : {dpnp.ndarray, usm_ndarray} + 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. +order : ({'C', 'F', 'A', 'K'}, optional): + Memory layout of the newly output array, if parameter `out` is `None`. + Default: "K" + +Returns +------- +out : dpnp.ndarray + The reciprocal square-root, element-wise. + +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 +-------- +:obj:`dpnp.sqrt` : Return the positive square-root of an array, element-wise. +:obj:`dpnp.reciprocal` : Return the reciprocal of an array, element-wise. + +Examples +-------- +>>> import dpnp as np +>>> x = np.array([1, 8, 27]) +>>> np.rsqrt(x) +array([1. , 0.35355338, 0.19245009]) +""" - return check_nd_call_func( - None, - dpnp_rsqrt, - x, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) +rsqrt = DPNPUnaryFunc( + "rsqrt", + ti._rsqrt_result_type, + ti._rsqrt, + _RSQRT_DOCSTRING, +) def rad2deg(x1): @@ -1625,7 +1480,7 @@ def rad2deg(x1): return degrees(x1) -def radians(x1): +def radians(x1, **kwargs): """ Convert angles from degrees to radians. @@ -1651,371 +1506,332 @@ def radians(x1): x1_desc = dpnp.get_dpnp_descriptor( x1, copy_when_strides=False, copy_when_nondefault_queue=False ) - if x1_desc: + if kwargs: + pass + elif x1_desc: return dpnp_radians(x1_desc).get_pyobj() return call_origin(numpy.radians, x1, **kwargs) -def sin( - x, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Trigonometric sine, element-wise. - - For full documentation refer to :obj:`numpy.sin`. - - Returns - ------- - out : dpnp.ndarray - The sine of each element of `x`. - - Limitations - ----------- - Parameter `x` is only supported as either :class:`dpnp.ndarray` or :class:`dpctl.tensor.usm_ndarray`. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Keyword argument `kwargs` is currently unsupported. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. - - See Also - -------- - :obj:`dpnp.arcsin` : 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. - - Examples - -------- - >>> import dpnp as np - >>> x = np.array([0, np.pi/2, np.pi]) - >>> np.sin(x) - array([ 0.000000e+00, 1.000000e+00, -8.742278e-08]) - - """ - - return check_nd_call_func( - numpy.sin, - dpnp_sin, - x, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) - - -def sinh( - x, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Hyperbolic sine, element-wise. - - For full documentation refer to :obj:`numpy.sinh`. - - Returns - ------- - out : dpnp.ndarray - The hyperbolic sine of each element of `x`. - - Limitations - ----------- - Parameter `x` is only supported as either :class:`dpnp.ndarray` or :class:`dpctl.tensor.usm_ndarray`. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Keyword argument `kwargs` is currently unsupported. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. - - See Also - -------- - :obj:`dpnp.arcsinh` : 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. - - Examples - -------- - >>> import dpnp as np - >>> x = np.array([0, np.pi/2, np.pi]) - >>> np.sinh(x) - array([0.0, 2.3012989, 11.548739]) - - """ - - return check_nd_call_func( - numpy.sinh, - dpnp_sinh, - x, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) - - -def sqrt( - x, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Return the non-negative square-root of an array, element-wise. - - For full documentation refer to :obj:`numpy.sqrt`. - - Returns - ------- - out : dpnp.ndarray - An array of the same shape as `x`, containing the positive - square-root of each element in `x`. If any element in `x` is - complex, a complex array is returned (and the square-roots of - negative reals are calculated). If all of the elements in `x` - are real, so is `y`, with negative elements returning ``nan``. - - Limitations - ----------- - Input array is supported as either :class:`dpnp.ndarray` or :class:`dpctl.tensor.usm_ndarray`. - Parameter `out` is supported as class:`dpnp.ndarray`, class:`dpctl.tensor.usm_ndarray` or - with default value ``None``. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. - - 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. - - Examples - -------- - >>> import dpnp as np - >>> x = np.array([1, 4, 9]) - >>> np.sqrt(x) - array([1., 2., 3.]) - - >>> x2 = np.array([4, -1, np.inf]) - >>> np.sqrt(x2) - array([ 2., nan, inf]) - - """ - - return check_nd_call_func( - numpy.sqrt, - dpnp_sqrt, - x, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) - - -def square( - x, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Return the element-wise square of the input. - - For full documentation refer to :obj:`numpy.square`. - - Returns - ------- - out : dpnp.ndarray - Element-wise `x * x`, of the same shape and dtype as `x`. - - Limitations - ----------- - Input array is supported as either :class:`dpnp.ndarray` or :class:`dpctl.tensor.usm_ndarray`. - Parameter `out` is supported as class:`dpnp.ndarray`, class:`dpctl.tensor.usm_ndarray` or - with default value ``None``. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. - - See Also - -------- - :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.power` : First array elements raised to powers - from second array, element-wise. - - Examples - -------- - >>> import dpnp as np - >>> x = np.array([-1j, 1]) - >>> np.square(x) - array([-1.+0.j, 1.+0.j]) - - """ - - return check_nd_call_func( - numpy.square, - dpnp_square, - x, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) - - -def tan( - x, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Trigonometric tangent, element-wise. +_SIN_DOCSTRING = """ +Computes sine for each element `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. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +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. + +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 +-------- +:obj:`dpnp.arcsin` : 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. + +Examples +-------- +>>> import dpnp as np +>>> x = np.array([0, np.pi/2, np.pi]) +>>> np.sin(x) +array([ 0.000000e+00, 1.000000e+00, -8.742278e-08]) +""" - For full documentation refer to :obj:`numpy.tan`. +sin = DPNPUnaryFunc( + "sin", + ti._sin_result_type, + ti._sin, + _SIN_DOCSTRING, + mkl_fn_to_call=vmi._mkl_sin_to_call, + mkl_impl_fn=vmi._sin, +) - Returns - ------- - out : dpnp.ndarray - The tangent of each element of `x`. - Limitations - ----------- - Parameter `x` is only supported as either :class:`dpnp.ndarray` or :class:`dpctl.tensor.usm_ndarray`. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Keyword argument `kwargs` is currently unsupported. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. +_SINH_DOCSTRING = """ +Computes hyperbolic sine for each element `x_i` for input array `x`. + +For full documentation refer to :obj:`numpy.sinh`. + +Parameters +---------- +x : {dpnp.ndarray, usm_ndarray} + Input array, expected to have numeric data type. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +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. + +Limitations +----------- +Keyword argument `kwargs` is currently unsupported. +Otherwise ``NotImplementedError`` exception will be raised. + +See Also +-------- +:obj:`dpnp.arcsinh` : 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. + +Examples +-------- +>>> import dpnp as np +>>> x = np.array([0, np.pi/2, np.pi]) +>>> np.sinh(x) +array([0.0, 2.3012989, 11.548739]) +""" - See Also - -------- - :obj:`dpnp.arctan` : 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. +sinh = DPNPUnaryFunc( + "sinh", + ti._sinh_result_type, + ti._sinh, + _SINH_DOCSTRING, + mkl_fn_to_call=vmi._mkl_sinh_to_call, + mkl_impl_fn=vmi._sinh, +) - Examples - -------- - >>> import dpnp as np - >>> x = np.array([-np.pi, np.pi/2, np.pi]) - >>> np.tan(x) - array([1.22460635e-16, 1.63317787e+16, -1.22460635e-16]) - """ +_SQRT_DOCSTRING = """ +Computes the non-negative square-root for each element `x_i` for input array `x`. + +For full documentation refer to :obj:`numpy.sqrt`. + +Parameters +---------- +x : {dpnp.ndarray, usm_ndarray} + Input array. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +Returns +------- +out : dpnp.ndarray + An array containing the element-wise square-root results. + +Limitations +----------- +Parameters `where` and `subok` are supported with their default values. +Otherwise ``NotImplementedError`` exception will be raised. + +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. + +Examples +-------- +>>> import dpnp as np +>>> x = np.array([1, 4, 9]) +>>> np.sqrt(x) +array([1., 2., 3.]) + +>>> x2 = np.array([4, -1, np.inf]) +>>> np.sqrt(x2) +array([ 2., nan, inf]) +""" - return check_nd_call_func( - numpy.tan, - dpnp_tan, - x, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) +sqrt = DPNPUnaryFunc( + "sqrt", + ti._sqrt_result_type, + ti._sqrt, + _SQRT_DOCSTRING, + mkl_fn_to_call=vmi._mkl_sqrt_to_call, + mkl_impl_fn=vmi._sqrt, +) -def tanh( - x, - /, - out=None, - *, - order="K", - where=True, - dtype=None, - subok=True, - **kwargs, -): - """ - Compute hyperbolic tangent element-wise. +_SQUARE_DOCSTRING = """ +Computes `x_i**2` (or `x_i*x_i`) for each element `x_i` of input array `x`. + +For full documentation refer to :obj:`numpy.square`. + +Parameters +---------- +x : {dpnp.ndarray, usm_ndarray} + Input array. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +Returns +------- +out : dpnp.ndarray + An array containing the element-wise square results. + +Limitations +----------- +Parameters `where` and `subok` are supported with their default values. +Otherwise ``NotImplementedError`` exception will be raised. + +See Also +-------- +: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.power` : First array elements raised to powers + from second array, element-wise. + +Examples +-------- +>>> import dpnp as np +>>> x = np.array([-1j, 1]) +>>> np.square(x) +array([-1.+0.j, 1.+0.j]) +""" - For full documentation refer to :obj:`numpy.tanh`. +square = DPNPUnaryFunc( + "square", + ti._square_result_type, + ti._square, + _SQUARE_DOCSTRING, + mkl_fn_to_call=vmi._mkl_sqr_to_call, + mkl_impl_fn=vmi._sqr, +) - Returns - ------- - out : dpnp.ndarray - The hyperbolic tangent of each element of `x`. - Limitations - ----------- - Parameter `x` is only supported as either :class:`dpnp.ndarray` or :class:`dpctl.tensor.usm_ndarray`. - Parameters `where`, `dtype` and `subok` are supported with their default values. - Keyword argument `kwargs` is currently unsupported. - Otherwise the function will be executed sequentially on CPU. - Input array data types are limited by supported DPNP :ref:`Data types`. +_TAN_DOCSTRING = """ +Computes tangent for each element `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. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +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. + +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 +-------- +:obj:`dpnp.arctan` : 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. + +Examples +-------- +>>> import dpnp as np +>>> x = np.array([-np.pi, np.pi/2, np.pi]) +>>> np.tan(x) +array([1.22460635e-16, 1.63317787e+16, -1.22460635e-16]) +""" - See Also - -------- - :obj:`dpnp.arctanh` : 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. +tan = DPNPUnaryFunc( + "tan", + ti._tan_result_type, + ti._tan, + _TAN_DOCSTRING, + mkl_fn_to_call=vmi._mkl_tan_to_call, + mkl_impl_fn=vmi._tan, +) - Examples - -------- - >>> import dpnp as np - >>> x = np.array([0, -np.pi, np.pi/2, np.pi]) - >>> np.tanh(x) - array([0.0, -0.996272, 0.917152, 0.996272]) - """ +_TANH_DOCSTRING = """ +Computes hyperbolic tangent for each element `x_i` for input array `x`. + +For full documentation refer to :obj:`numpy.tanh`. + +Parameters +---------- +x : {dpnp.ndarray, usm_ndarray} + Input array, expected to have numeric data type. +out : {None, dpnp.ndarray}, optional + Output array to populate. + Array must have the correct shape and the expected data type. +order : {"C", "F", "A", "K"}, optional + Memory layout of the newly output array, if parameter `out` is ``None``. + Default: "K". + +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. + +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 +-------- +:obj:`dpnp.arctanh` : 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. + +Examples +-------- +>>> import dpnp as np +>>> x = np.array([0, -np.pi, np.pi/2, np.pi]) +>>> np.tanh(x) +array([0.0, -0.996272, 0.917152, 0.996272]) +""" - return check_nd_call_func( - numpy.tanh, - dpnp_tanh, - x, - out=out, - where=where, - order=order, - dtype=dtype, - subok=subok, - **kwargs, - ) +tanh = DPNPUnaryFunc( + "tanh", + ti._tanh_result_type, + ti._tanh, + _TANH_DOCSTRING, + mkl_fn_to_call=vmi._mkl_tanh_to_call, + mkl_impl_fn=vmi._tanh, +) -def unwrap(x1): +def unwrap(x1, **kwargs): """ Unwrap by changing deltas between values to 2*pi complement. @@ -2044,7 +1860,9 @@ def unwrap(x1): """ x1_desc = dpnp.get_dpnp_descriptor(x1, copy_when_nondefault_queue=False) - if x1_desc: + if kwargs: + pass + elif x1_desc: return dpnp_unwrap(x1_desc).get_pyobj() return call_origin(numpy.unwrap, x1, **kwargs) diff --git a/tests/test_mathematical.py b/tests/test_mathematical.py index 3343e1c81773..0968f0fe2807 100644 --- a/tests/test_mathematical.py +++ b/tests/test_mathematical.py @@ -585,7 +585,7 @@ def test_remainder(self, dtype, lhs, rhs): def test_power(self, dtype, lhs, rhs): self._test_mathematical("power", dtype, lhs, rhs, check_type=False) - @pytest.mark.parametrize("dtype", get_all_dtypes()) + @pytest.mark.parametrize("dtype", get_all_dtypes(no_bool=True)) def test_subtract(self, dtype, lhs, rhs): self._test_mathematical("subtract", dtype, lhs, rhs, check_type=False) @@ -930,7 +930,6 @@ def test_prod_nanprod_Error(self): ids=["[2, 0, -2]", "[1.1, -1.1]"], ) @pytest.mark.parametrize("dtype", get_all_dtypes(no_bool=True)) -@pytest.mark.usefixtures("allow_fall_back_on_numpy") def test_sign(data, dtype): np_a = numpy.array(data, dtype=dtype) dpnp_a = dpnp.array(data, dtype=dtype) @@ -3171,3 +3170,76 @@ def test_matmul_axes(self): axes = [(1, 0), (0), (0, 1)] with pytest.raises(ValueError): dpnp.matmul(a, b, axes=axes) + + +def test_elemenwise_nin_nout(): + assert dpnp.abs.nin == 1 + assert dpnp.add.nin == 2 + + assert dpnp.abs.nout == 1 + assert dpnp.add.nout == 1 + + +def test_elemenwise_error(): + x = dpnp.array([1, 2, 3]) + out = dpnp.array([1, 2, 3]) + + with pytest.raises(NotImplementedError): + dpnp.abs(x, unknown_kwarg=1) + with pytest.raises(NotImplementedError): + dpnp.abs(x, where=False) + with pytest.raises(NotImplementedError): + dpnp.abs(x, subok=False) + with pytest.raises(TypeError): + dpnp.abs(1) + with pytest.raises(TypeError): + dpnp.abs([1, 2]) + with pytest.raises(TypeError): + dpnp.abs(x, out=out, dtype="f4") + with pytest.raises(ValueError): + dpnp.abs(x, order="H") + + with pytest.raises(NotImplementedError): + dpnp.add(x, x, unknown_kwarg=1) + with pytest.raises(NotImplementedError): + dpnp.add(x, x, where=False) + with pytest.raises(NotImplementedError): + dpnp.add(x, x, subok=False) + with pytest.raises(TypeError): + dpnp.add(1, 2) + with pytest.raises(TypeError): + dpnp.add([1, 2], [1, 2]) + with pytest.raises(TypeError): + dpnp.add(x, [1, 2]) + with pytest.raises(TypeError): + dpnp.add([1, 2], x) + with pytest.raises(TypeError): + dpnp.add(x, x, out=out, dtype="f4") + with pytest.raises(ValueError): + dpnp.add(x, x, order="H") + + +def test_elemenwise_order_none(): + x_np = numpy.array([1, 2, 3]) + x = dpnp.array([1, 2, 3]) + + result = dpnp.abs(x, order=None) + expected = numpy.abs(x_np, order=None) + assert_dtype_allclose(result, expected) + + result = dpnp.add(x, x, order=None) + expected = numpy.add(x_np, x_np, order=None) + assert_dtype_allclose(result, expected) + + +def test_bitwise_1array_input(): + x = dpnp.array([1, 2, 3]) + x_np = numpy.array([1, 2, 3]) + + result = dpnp.add(x, 1, dtype="f4") + expected = numpy.add(x_np, 1, dtype="f4") + assert_dtype_allclose(result, expected) + + result = dpnp.add(1, x, dtype="f4") + expected = numpy.add(1, x_np, dtype="f4") + assert_dtype_allclose(result, expected) diff --git a/tests/third_party/cupy/core_tests/test_ndarray_math.py b/tests/third_party/cupy/core_tests/test_ndarray_math.py index 5ed98f374bf9..3233687789ab 100644 --- a/tests/third_party/cupy/core_tests/test_ndarray_math.py +++ b/tests/third_party/cupy/core_tests/test_ndarray_math.py @@ -15,7 +15,6 @@ } ) ) -@pytest.mark.usefixtures("allow_fall_back_on_numpy") class TestRound(unittest.TestCase): shape = (20,) @@ -33,7 +32,7 @@ def test_round(self, xp, dtype): a = testing.shaped_random(self.shape, xp, scale=100, dtype=dtype) return a.round(self.decimals) - @testing.numpy_cupy_array_equal() + @testing.numpy_cupy_allclose(atol=1e-5) def test_round_out(self, xp): dtype = "d" if has_support_aspect64() else "f" a = testing.shaped_random(self.shape, xp, scale=100, dtype=dtype) @@ -52,13 +51,16 @@ def test_round_out(self, xp): } ) ) -@pytest.mark.usefixtures("allow_fall_back_on_numpy") class TestRoundHalfway(unittest.TestCase): shape = (20,) @testing.for_float_dtypes() - @testing.numpy_cupy_array_equal() + @testing.numpy_cupy_allclose(atol=1e-5) def test_round_halfway_float(self, xp, dtype): + if self.decimals is -3 and dtype == numpy.float32: + pytest.skip( + "Case with decimals=-3 and dtype float32 has divide error less than 1e-5" + ) # generate [..., -1.5, -0.5, 0.5, 1.5, ...] * 10^{-decimals} a = testing.shaped_arange(self.shape, xp, dtype=dtype) a *= 2 @@ -76,6 +78,10 @@ def test_round_halfway_float(self, xp, dtype): @testing.numpy_cupy_array_equal() def test_round_halfway_int(self, xp, dtype): # generate [..., -1.5, -0.5, 0.5, 1.5, ...] * 10^{-decimals} + if self.decimals is -3 and not has_support_aspect64(): + pytest.skip( + "Case with decimals=-3 and dtype float32 has divide error less than 1e-5" + ) a = testing.shaped_arange(self.shape, xp, dtype=dtype) a *= 2 a -= a.size + 1 @@ -90,6 +96,10 @@ def test_round_halfway_int(self, xp, dtype): @testing.numpy_cupy_array_equal() def test_round_halfway_uint(self, xp, dtype): # generate [0.5, 1.5, ...] * 10^{-decimals} + if self.decimals is -3 and not has_support_aspect64(): + pytest.skip( + "Case with decimals=-3 and dtype float32 has divide error less than 1e-5" + ) a = testing.shaped_arange(self.shape, xp, dtype=dtype) a *= 2 a -= 1 diff --git a/tests/third_party/cupy/math_tests/test_arithmetic.py b/tests/third_party/cupy/math_tests/test_arithmetic.py index e957c9d935bd..ac5670dd95e2 100644 --- a/tests/third_party/cupy/math_tests/test_arithmetic.py +++ b/tests/third_party/cupy/math_tests/test_arithmetic.py @@ -17,7 +17,7 @@ all_types = float_types + int_types + complex_types negative_types_wo_fp16 = ( [numpy.bool_] - + [numpy.float32, numpy.float64] + + float_types + [numpy.int16, numpy.int32, numpy.int64] + complex_types ) @@ -128,8 +128,7 @@ class TestArithmeticUnary: @testing.numpy_cupy_allclose(atol=1e-5, type_check=has_support_aspect64()) def test_unary(self, xp): arg1 = self.arg1 - if isinstance(arg1, numpy.ndarray): - arg1 = xp.asarray(arg1) + arg1 = xp.asarray(arg1) if self.name in ("reciprocal") and xp is numpy: # In Numpy, for integer arguments with absolute value larger than 1 the result is always zero. @@ -224,15 +223,13 @@ def check_binary(self, xp): # TODO(niboshi): Fix this: xp.add(0j, xp.array([2.], 'f')).dtype # numpy => complex64 - # cupy => complex128 - if isinstance(arg1, complex): - if dtype2 in (numpy.float16, numpy.float32): - return xp.array(True) + # # cupy => complex128 + # if isinstance(arg1, complex): + # if dtype2 in (numpy.float16, numpy.float32): + # return xp.array(True) - if isinstance(arg1, numpy.ndarray): - arg1 = xp.asarray(arg1) - if isinstance(arg2, numpy.ndarray): - arg2 = xp.asarray(arg2) + arg1 = xp.asarray(arg1) + arg2 = xp.asarray(arg2) # Subtraction between booleans is not allowed. if ( @@ -326,7 +323,7 @@ def test_binary(self): ] + [0, 0.0, 2, 2.0, -2, -2.0], "name": ["true_divide"], - "dtype": [numpy.float64], + "dtype": float_types, "use_dtype": [True, False], } ) @@ -343,7 +340,7 @@ def test_binary(self): ] + [0.0, 2.0, -2.0], "name": ["power", "true_divide", "subtract"], - "dtype": [numpy.float64], + "dtype": float_types, "use_dtype": [True, False], } ) @@ -360,7 +357,7 @@ def test_binary(self): ] + [0, 0.0, 2, 2.0, -2, -2.0], "name": ["floor_divide", "fmod", "remainder", "mod"], - "dtype": [numpy.float64], + "dtype": float_types, "use_dtype": [True, False], } ) @@ -377,7 +374,7 @@ def test_binary(self): ] + [0, 0.0, 2, 2.0, -2, -2.0], "name": ["floor_divide", "fmod", "remainder", "mod"], - "dtype": [numpy.float64], + "dtype": float_types, "use_dtype": [True, False], } ) diff --git a/tests/third_party/cupy/math_tests/test_misc.py b/tests/third_party/cupy/math_tests/test_misc.py index 241457fbad90..dd7fe9dcc1aa 100644 --- a/tests/third_party/cupy/math_tests/test_misc.py +++ b/tests/third_party/cupy/math_tests/test_misc.py @@ -26,11 +26,15 @@ def check_binary(self, name, xp, dtype, no_bool=False): @testing.for_dtypes(["?", "b", "h", "i", "q", "e", "f", "d", "F", "D"]) @testing.numpy_cupy_allclose(atol=1e-5) - def check_unary_negative(self, name, xp, dtype, no_bool=False): + def check_unary_negative( + self, name, xp, dtype, no_bool=False, no_complex=False + ): if no_bool and numpy.dtype(dtype).char == "?": return numpy.int_(0) a = xp.array([-3, -2, -1, 1, 2, 3], dtype=dtype) if numpy.dtype(dtype).kind == "c": + if no_complex: + return numpy.int_(0) a += (a * 1j).astype(dtype) return getattr(xp, name)(a) @@ -194,9 +198,9 @@ def test_fabs_negative(self, xp, dtype): def test_sign(self): self.check_unary("sign", no_bool=True) - @pytest.mark.usefixtures("allow_fall_back_on_numpy") + # TODO: remove no_comlex=True, when numpy 2.0.0 will release def test_sign_negative(self): - self.check_unary_negative("sign", no_bool=True) + self.check_unary_negative("sign", no_bool=True, no_complex=True) def test_maximum(self): self.check_binary("maximum") diff --git a/tests/third_party/cupy/math_tests/test_rounding.py b/tests/third_party/cupy/math_tests/test_rounding.py index 7e451ae1e511..74ebf8e745f8 100644 --- a/tests/third_party/cupy/math_tests/test_rounding.py +++ b/tests/third_party/cupy/math_tests/test_rounding.py @@ -84,7 +84,6 @@ def test_round(self): } ) ) -@pytest.mark.usefixtures("allow_fall_back_on_numpy") class TestRound(unittest.TestCase): shape = (20,) @@ -102,7 +101,7 @@ def test_round(self, xp, dtype): a = testing.shaped_random(self.shape, xp, scale=100, dtype=dtype) return xp.around(a, self.decimals) - @testing.numpy_cupy_array_equal() + @testing.numpy_cupy_allclose(atol=1e-5) def test_round_out(self, xp): dtype = "d" if has_support_aspect64() else "f" a = testing.shaped_random(self.shape, xp, scale=100, dtype=dtype) @@ -118,7 +117,9 @@ def test_round_out(self, xp): } ) ) -@pytest.mark.usefixtures("allow_fall_back_on_numpy") +@pytest.mark.skipif( + not has_support_aspect64(), reason="overflow encountered for float32 dtype" +) class TestRoundExtreme(unittest.TestCase): shape = (20,) @@ -158,11 +159,11 @@ def test_round_small(self, xp, dtype): } ) ) -@pytest.mark.usefixtures("allow_fall_back_on_numpy") class TestRoundBorder(unittest.TestCase): @testing.numpy_cupy_allclose(atol=1e-5, type_check=has_support_aspect64()) def test_around_positive1(self, xp): a, decimals = self.value + a = xp.asarray(a) return xp.around(a, decimals) @testing.numpy_cupy_allclose(atol=1e-5, type_check=has_support_aspect64()) @@ -174,6 +175,7 @@ def test_around_positive2(self, xp): @testing.numpy_cupy_allclose(atol=1e-5, type_check=has_support_aspect64()) def test_around_negative1(self, xp): a, decimals = self.value + a = xp.asarray(a) return xp.around(-a, decimals) @testing.numpy_cupy_allclose(atol=1e-5, type_check=has_support_aspect64())