Source code for dpnp.dpnp_iface_trigonometric

# -*- coding: utf-8 -*-
# *****************************************************************************
# Copyright (c) 2016-2024, Intel Corporation
# All rights reserved.
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions are met:
# - Redistributions of source code must retain the above copyright notice,
#   this list of conditions and the following disclaimer.
# - Redistributions in binary form must reproduce the above copyright notice,
#   this list of conditions and the following disclaimer in the documentation
#   and/or other materials provided with the distribution.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
# THE POSSIBILITY OF SUCH DAMAGE.
# *****************************************************************************

"""
Interface of the Trigonometric part of the DPNP

Notes
-----
This module is a face or public interface file for the library
it contains:
 - Interface functions
 - documentation for the functions
 - The functions parameters check

"""

# pylint: disable=protected-access
# 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 dpnp
import dpnp.backend.extensions.ufunc._ufunc_impl as ufi

from .dpnp_algo.dpnp_elementwise_common import DPNPBinaryFunc, DPNPUnaryFunc
from .dpnp_utils.dpnp_utils_reduction import dpnp_wrap_reduction_call

__all__ = [
    "arccos",
    "arccosh",
    "arcsin",
    "arcsinh",
    "arctan",
    "arctan2",
    "arctanh",
    "asin",
    "asinh",
    "acos",
    "acosh",
    "atan",
    "atan2",
    "atanh",
    "cbrt",
    "cos",
    "cosh",
    "cumlogsumexp",
    "deg2rad",
    "degrees",
    "exp",
    "exp2",
    "expm1",
    "hypot",
    "log",
    "log10",
    "log1p",
    "log2",
    "logaddexp",
    "logaddexp2",
    "logsumexp",
    "rad2deg",
    "radians",
    "reciprocal",
    "reduce_hypot",
    "rsqrt",
    "sin",
    "sinh",
    "sqrt",
    "square",
    "tan",
    "tanh",
    "unwrap",
]


def _get_accumulation_res_dt(a, dtype):
    """Get a dtype used by dpctl for result array in accumulation function."""

    if dtype is None:
        return dtu._default_accumulation_dtype_fp_types(a.dtype, a.sycl_queue)

    dtype = dpnp.dtype(dtype)
    return dtu._to_device_supported_dtype(dtype, a.sycl_device)


_ACOS_DOCSTRING = r"""
Computes inverse cosine for each element `x_i` for input array `x`.

The inverse of :obj:`dpnp.cos` so that, if ``y = cos(x)``, then ``x = arccos(y)``.
Note that :obj:`dpnp.acos` is an alias of :obj:`dpnp.arccos`.

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, usm_ndarray}, optional
    Output array to populate.
    Array must have the correct shape and the expected data type.
    Default: ``None``.
order : {"C", "F", "A", "K"}, optional
    Memory layout of the newly output array, if parameter `out` is ``None``.
    Default: ``"K"``.

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.

Notes
-----
:obj:`dpnp.arccos` is a multivalued function: for each `x` there are infinitely
many numbers `z` such that ``cos(z) = x``. The convention is to return the
angle `z` whose real part lies in `[0, pi]`.

For real-valued input data types, :obj:`dpnp.arccos` always returns real output.
For each value that cannot be expressed as a real number or infinity, it yields
``nan``.

For complex-valued input, :obj:`dpnp.arccos` is a complex analytic function that
has, by convention, the branch cuts `[-inf, -1]` and `[1, inf]` and is continuous
from above on the former and from below on the latter.

The inverse cos is also known as :math:`acos` or :math:`cos^{-1}`.

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="_mkl_acos_to_call",
    mkl_impl_fn="_acos",
)

acos = arccos  # acos is an alias for arccos


_ACOSH_DOCSTRING = r"""
Computes inverse hyperbolic cosine for each element `x_i` for input array `x`.

The inverse of :obj:`dpnp.cosh` so that, if ``y = cosh(x)``, then ``x = arccosh(y)``.
Note that :obj:`dpnp.acosh` is an alias of :obj:`dpnp.arccosh`.

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, usm_ndarray}, optional
    Output array to populate.
    Array must have the correct shape and the expected data type.
    Default: ``None``.
order : {"C", "F", "A", "K"}, optional
    Memory layout of the newly output array, if parameter `out` is ``None``.
    Default: ``"K"``.

Returns
-------
out : dpnp.ndarray
    An array containing the element-wise inverse hyperbolic cosine, in
    radians and in the half-closed interval `[0, inf)`. The data type
    of the returned array is determined by the Type Promotion Rules.

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.arcsinh` : Hyperbolic inverse sine, element-wise.
:obj:`dpnp.sinh` : Hyperbolic sine, element-wise.
:obj:`dpnp.arctanh` : Hyperbolic inverse tangent, element-wise.
:obj:`dpnp.tanh` : Hyperbolic tangent, element-wise.
:obj:`dpnp.arccos` : Trigonometric inverse cosine, element-wise.

Notes
-----
:obj:`dpnp.arccosh` is a multivalued function: for each `x` there are infinitely
many numbers `z` such that ``cosh(z) = x``. The convention is to return the
angle `z` whose real part lies in `[0, inf]`.

For real-valued input data types, :obj:`dpnp.arccosh` always returns real output.
For each value that cannot be expressed as a real number or infinity, it yields
``nan``.

For complex-valued input, :obj:`dpnp.arccosh` is a complex analytic function that
has, by convention, the branch cuts `[-inf, 1]` and is continuous from above.

The inverse hyperbolic cos is also known as :math:`acosh` or :math:`cosh^{-1}`.

Examples
--------
>>> import dpnp as np
>>> x = np.array([1.0, np.e, 10.0])
>>> np.arccosh(x)
array([0.0, 1.65745445, 2.99322285])
"""

arccosh = DPNPUnaryFunc(
    "arccosh",
    ti._acosh_result_type,
    ti._acosh,
    _ACOSH_DOCSTRING,
    mkl_fn_to_call="_mkl_acosh_to_call",
    mkl_impl_fn="_acosh",
)

acosh = arccosh  # acosh is an alias for arccosh


_ASIN_DOCSTRING = r"""
Computes inverse sine for each element `x_i` for input array `x`.

The inverse of :obj:`dpnp.sin`, so that if ``y = sin(x)`` then ``x = arcsin(y)``.
Note that :obj:`dpnp.asin` is an alias of :obj:`dpnp.arcsin`.

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, usm_ndarray}, optional
    Output array to populate.
    Array must have the correct shape and the expected data type.
    Default: ``None``.
order : {"C", "F", "A", "K"}, optional
    Memory layout of the newly output array, if parameter `out` is ``None``.
    Default: ``"K"``.

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.cos` : Trigonometric cosine, element-wise.
:obj:`dpnp.arccos` : Trigonometric inverse cosine, element-wise.
:obj:`dpnp.tan` : Trigonometric tangent, element-wise.
:obj:`dpnp.arctan` : Trigonometric inverse tangent, element-wise.
:obj:`dpnp.arctan2` : Element-wise arc tangent of `x1/x2` choosing the quadrant correctly.
:obj:`dpnp.arcsinh` : Hyperbolic inverse sine, element-wise.

Notes
-----
:obj:`dpnp.arcsin` is a multivalued function: for each `x` there are infinitely
many numbers `z` such that ``sin(z) = x``. The convention is to return the
angle `z` whose real part lies in `[-pi/2, pi/2]`.

For real-valued input data types, :obj:`dpnp.arcsin` always returns real output.
For each value that cannot be expressed as a real number or infinity, it yields
``nan``.

For complex-valued input, :obj:`dpnp.arcsin` is a complex analytic function that
has, by convention, the branch cuts `[-inf, -1]` and `[1, inf]` and is continuous
from above on the former and from below on the latter.

The inverse sine is also known as :math:`asin` or :math:`sin^{-1}`.

Examples
--------
>>> import dpnp as np
>>> x = np.array([0, 1, -1])
>>> np.arcsin(x)
array([0.0, 1.5707963267948966, -1.5707963267948966])
"""

arcsin = DPNPUnaryFunc(
    "arcsin",
    ti._asin_result_type,
    ti._asin,
    _ASIN_DOCSTRING,
    mkl_fn_to_call="_mkl_asin_to_call",
    mkl_impl_fn="_asin",
)

asin = arcsin  # asin is an alias for arcsin


_ASINH_DOCSTRING = r"""
Computes inverse hyperbolic sine for each element `x_i` for input array `x`.

The inverse of :obj:`dpnp.sinh`, so that if ``y = sinh(x)`` then ``x = arcsinh(y)``.
Note that :obj:`dpnp.asinh` is an alias of :obj:`dpnp.arcsinh`.

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, usm_ndarray}, optional
    Output array to populate.
    Array must have the correct shape and the expected data type.
    Default: ``None``.
order : {"C", "F", "A", "K"}, optional
    Memory layout of the newly output array, if parameter `out` is ``None``.
    Default: ``"K"``.

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.

Notes
-----
:obj:`dpnp.arcsinh` is a multivalued function: for each `x` there are infinitely
many numbers `z` such that ``sin(z) = x``. The convention is to return the
angle `z` whose real part lies in `[-pi/2, pi/2]`.

For real-valued input data types, :obj:`dpnp.arcsinh` always returns real output.
For each value that cannot be expressed as a real number or infinity, it yields
``nan``.

For complex-valued input, :obj:`dpnp.arcsinh` is a complex analytic function that
has, by convention, the branch cuts `[1j, infj]` and `[`1j, -infj]` and is continuous
from above on the former and from below on the latter.

The inverse hyperbolic sine is also known as :math:`asinh` or :math:`sinh^{-1}`.


Examples
--------
>>> import dpnp as np
>>> x = np.array([np.e, 10.0])
>>> np.arcsinh(x)
array([1.72538256, 2.99822295])
"""

arcsinh = DPNPUnaryFunc(
    "arcsinh",
    ti._asinh_result_type,
    ti._asinh,
    _ASINH_DOCSTRING,
    mkl_fn_to_call="_mkl_asinh_to_call",
    mkl_impl_fn="_asinh",
)

asinh = arcsinh  # asinh is an alias for arcsinh


_ATAN_DOCSTRING = r"""
Computes inverse tangent for each element `x_i` for input array `x`.

The inverse of :obj:`dpnp.tan`, so that if ``y = tan(x)`` then ``x = arctan(y)``.
Note that :obj:`dpnp.atan` is an alias of :obj:`dpnp.arctan`.

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, usm_ndarray}, optional
    Output array to populate.
    Array must have the correct shape and the expected data type.
    Default: ``None``.
order : {"C", "F", "A", "K"}, optional
    Memory layout of the newly output array, if parameter `out` is ``None``.
    Default: ``"K"``.

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.

Notes
-----
:obj:`dpnp.arctan` is a multivalued function: for each `x` there are infinitely
many numbers `z` such that ``tan(z) = x``. The convention is to return the
angle `z` whose real part lies in `[-pi/2, pi/2]`.

For real-valued input data types, :obj:`dpnp.arctan` always returns real output.
For each value that cannot be expressed as a real number or infinity, it yields
``nan``.

For complex-valued input, :obj:`dpnp.arctan` is a complex analytic function that
has, by convention, the branch cuts `[1j, infj]` and `[-1j, -infj]`  and is continuous
from the left on the former and from the right on the latter.

The inverse tan is also known as :math:`atan` or :math:`tan^{-1}`.

Examples
--------
>>> import dpnp as np
>>> x = np.array([0, 1])
>>> np.arctan(x)
array([0.0, 0.78539816])
"""

arctan = DPNPUnaryFunc(
    "arctan",
    ti._atan_result_type,
    ti._atan,
    _ATAN_DOCSTRING,
    mkl_fn_to_call="_mkl_atan_to_call",
    mkl_impl_fn="_atan",
)

atan = arctan  # atan is an alias for arctan


_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.

Note that :obj:`dpnp.atan2` is an alias of :obj:`dpnp.arctan2`.
This function is not defined for complex-valued arguments; for the so-called
argument of complex values, use :obj:`dpnp.angle`.

For full documentation refer to :obj:`numpy.arctan2`.

Parameters
----------
x1 : {dpnp.ndarray, usm_ndarray, scalar}
    First input array, expected to have a real-valued floating-point
    data type.
    Both inputs `x1` and `x2` can not be scalars at the same time.
x2 : {dpnp.ndarray, usm_ndarray, scalar}
    Second input array, also expected to have a real-valued
    floating-point data type.
    Both inputs `x1` and `x2` can not be scalars at the same time.
    If ``x1.shape != x2.shape``, they must be broadcastable to a common shape
    (which becomes the shape of the output).
out : {None, dpnp.ndarray, usm_ndarray}, optional
    Output array to populate.
    Array must have the correct shape and the expected data type.
    Default: ``None``.
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.])
"""

arctan2 = DPNPBinaryFunc(
    "arctan2",
    ti._atan2_result_type,
    ti._atan2,
    _ATAN2_DOCSTRING,
    mkl_fn_to_call="_mkl_atan2_to_call",
    mkl_impl_fn="_atan2",
)

atan2 = arctan2  # atan2 is an alias for arctan2


_ATANH_DOCSTRING = r"""
Computes hyperbolic inverse tangent for each element `x_i` for input array `x`.

The inverse of :obj:`dpnp.tanh`, so that if ``y = tanh(x)`` then ``x = arctanh(y)``.
Note that :obj:`dpnp.atanh` is an alias of :obj:`dpnp.arctanh`.

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, usm_ndarray}, optional
    Output array to populate.
    Array must have the correct shape and the expected data type.
    Default: ``None``.
order : {"C", "F", "A", "K"}, optional
    Memory layout of the newly output array, if parameter `out` is ``None``.
    Default: ``"K"``.

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.

Notes
-----
:obj:`dpnp.arctanh` is a multivalued function: for each `x` there are infinitely
many numbers `z` such that ``tanh(z) = x``. The convention is to return the
angle `z` whose real part lies in `[-pi/2, pi/2]`.

For real-valued input data types, :obj:`dpnp.arctanh` always returns real output.
For each value that cannot be expressed as a real number or infinity, it yields
``nan``.

For complex-valued input, :obj:`dpnp.arctanh` is a complex analytic function that
has, by convention, the branch cuts `[-1, -inf]` and `[1, inf]` and is is continuous
from above on the former and from below on the latter.

The inverse hyperbolic tan is also known as :math:`atanh` or :math:`tanh^{-1}`.

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="_mkl_atanh_to_call",
    mkl_impl_fn="_atanh",
)

atanh = arctanh  # atanh is an alias for arctanh


_CBRT_DOCSTRING = """
Computes positive cube-root for each element `x_i` for input array `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, usm_ndarray}, optional
    Output array to populate.
    Array must have the correct shape and the expected data type.
    Default: ``None``.
order : {"C", "F", "A", "K"}, optional
    Memory layout of the newly output array, if parameter `out` is ``None``.
    Default: ``"K"``.

Returns
-------
out : dpnp.ndarray
    An array containing the element-wise positive cube-root.
    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.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.])
"""

cbrt = DPNPUnaryFunc(
    "cbrt",
    ti._cbrt_result_type,
    ti._cbrt,
    _CBRT_DOCSTRING,
    mkl_fn_to_call="_mkl_cbrt_to_call",
    mkl_impl_fn="_cbrt",
)


_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, usm_ndarray}, optional
    Output array to populate.
    Array must have the correct shape and the expected data type.
    Default: ``None``.
order : {"C", "F", "A", "K"}, optional
    Memory layout of the newly output array, if parameter `out` is ``None``.
    Default: ``"K"``.

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="_mkl_cos_to_call",
    mkl_impl_fn="_cos",
)


_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, usm_ndarray}, optional
    Output array to populate.
    Array must have the correct shape and the expected data type.
    Default: ``None``.
order : {"C", "F", "A", "K"}, optional
    Memory layout of the newly output array, if parameter `out` is ``None``.
    Default: ``"K"``.

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])
"""

cosh = DPNPUnaryFunc(
    "cosh",
    ti._cosh_result_type,
    ti._cosh,
    _COSH_DOCSTRING,
    mkl_fn_to_call="_mkl_cosh_to_call",
    mkl_impl_fn="_cosh",
)


[docs] def cumlogsumexp( x, /, *, axis=None, dtype=None, include_initial=False, out=None ): """ Calculates the cumulative logarithm of the sum of elements in the input array `x`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} Input array, expected to have a real-valued data type. axis : {None, int}, optional Axis or axes along which values must be computed. If a tuple of unique integers, values are computed over multiple axes. If ``None``, the result is computed over the entire array. Default: ``None``. dtype : {None, dtype}, optional Data type of the returned array. If ``None``, the default data type is inferred from the "kind" of the input array data type. - If `x` has a real-valued floating-point data type, the returned array will have the same data type as `x`. - If `x` has a boolean or integral data type, the returned array will have the default floating point data type for the device where input array `x` is allocated. - If `x` has a complex-valued floating-point data type, an error is raised. If the data type (either specified or resolved) differs from the data type of `x`, the input array elements are cast to the specified data type before computing the result. Default: ``None``. include_initial : {None, bool}, optional A boolean indicating whether to include the initial value (i.e., the additive identity, zero) as the first value along the provided axis in the output. Default: ``False``. out : {None, dpnp.ndarray, usm_ndarray}, optional The array into which the result is written. The data type of `out` must match the expected shape and the expected data type of the result or (if provided) `dtype`. If ``None`` then a new array is returned. Default: ``None``. Returns ------- out : dpnp.ndarray An array containing the results. If the result was computed over the entire array, a zero-dimensional array is returned. The returned array has the data type as described in the `dtype` parameter description above. Note ---- This function is equivalent of `numpy.logaddexp.accumulate`. See Also -------- :obj:`dpnp.logsumexp` : Logarithm of the sum of elements of the inputs, element-wise. Examples -------- >>> import dpnp as np >>> a = np.ones(10) >>> np.cumlogsumexp(a) array([1. , 1.69314718, 2.09861229, 2.38629436, 2.60943791, 2.79175947, 2.94591015, 3.07944154, 3.19722458, 3.30258509]) """ dpnp.check_supported_arrays_type(x) if x.ndim > 1 and axis is None: usm_x = dpnp.ravel(x).get_array() else: usm_x = dpnp.get_usm_ndarray(x) return dpnp_wrap_reduction_call( usm_x, out, dpt.cumulative_logsumexp, _get_accumulation_res_dt(x, dtype), axis=axis, dtype=dtype, include_initial=include_initial, )
_DEG2RAD_DOCSTRING = """ Convert angles from degrees to radians. For full documentation refer to :obj:`numpy.deg2rad`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} Angles in degrees. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. Default: ``None``. order : {"C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. Default: ``"K"``. Returns ------- out : dpnp.ndarray The corresponding angle in radians. 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.rad2deg` : Convert angles from radians to degrees. :obj:`dpnp.unwrap` : Remove large jumps in angle by wrapping. :obj:`dpnp.radians` : Equivalent function. Notes ----- dpnp.deg2rad(x) is ``x * pi / 180``. Examples -------- >>> import dpnp as np >>> x = np.array(180) >>> np.deg2rad(x) array(3.14159265) """ deg2rad = DPNPUnaryFunc( "deg2rad", ufi._radians_result_type, ufi._radians, _DEG2RAD_DOCSTRING, ) _DEGREES_DOCSTRING = """ Convert angles from radians to degrees. For full documentation refer to :obj:`numpy.degrees`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} Input array in radians. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. Default: ``None``. order : {"C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. Default: ``"K"``. Returns ------- out : dpnp.ndarray The corresponding degree 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.rad2deg` : Equivalent function. Examples -------- >>> import dpnp as np >>> rad = np.arange(12.) * np.pi/6 Convert a radian array to degrees: >>> np.degrees(rad) array([ 0., 30., 60., 90., 120., 150., 180., 210., 240., 270., 300., 330.]) >>> out = np.zeros_like(rad) >>> r = np.degrees(rad, out) >>> np.all(r == out) array(True) """ degrees = DPNPUnaryFunc( "degrees", ufi._degrees_result_type, ufi._degrees, _DEGREES_DOCSTRING, ) _EXP_DOCSTRING = """ Computes the exponent 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, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. Default: ``None``. order : {"C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. Default: ``"K"``. Returns ------- out : dpnp.ndarray An array containing the element-wise exponent 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]) """ exp = DPNPUnaryFunc( "exp", ti._exp_result_type, ti._exp, _EXP_DOCSTRING, mkl_fn_to_call="_mkl_exp_to_call", mkl_impl_fn="_exp", ) _EXP2_DOCSTRING = """ Computes the base-2 exponent 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, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. Default: ``None``. order : {"C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. Default: ``"K"``. Returns ------- out : dpnp.ndarray An array containing the element-wise base-2 exponents. 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 exponent 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="_mkl_exp2_to_call", mkl_impl_fn="_exp2", ) _EXPM1_DOCSTRING = """ Computes the exponent 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, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. Default: ``None``. order : {"C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. Default: ``"K"``. 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 exponents for all elements in the array. :obj:`dpnp.exp2` : Calculate `2**x` for all elements in the array. :obj:`dpnp.log1p` : Calculate ``log(1 + x)``, the inverse of :obj:`dpnp.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) """ expm1 = DPNPUnaryFunc( "expm1", ti._expm1_result_type, ti._expm1, _EXPM1_DOCSTRING, mkl_fn_to_call="_mkl_expm1_to_call", mkl_impl_fn="_expm1", ) _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, scalar} First input array, expected to have a real-valued data type. Both inputs `x1` and `x2` can not be scalars at the same time. x2 : {dpnp.ndarray, usm_ndarray, scalar} Second input array, also expected to have a real-valued data type. Both inputs `x1` and `x2` can not be scalars at the same time. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. Default: ``None``. 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.]]) """ hypot = DPNPBinaryFunc( "hypot", ti._hypot_result_type, ti._hypot, _HYPOT_DOCSTRING, mkl_fn_to_call="_mkl_hypot_to_call", mkl_impl_fn="_hypot", ) _LOG_DOCSTRING = """ Computes the natural logarithm for each element `x_i` of input array `x`. 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, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. Default: ``None``. order : {"C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. Default: ``"K"``. 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="_mkl_ln_to_call", mkl_impl_fn="_ln", ) _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, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. Default: ``None``. order : {"C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. Default: ``"K"``. Returns ------- out : dpnp.ndarray An array containing the element-wise 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]) """ log10 = DPNPUnaryFunc( "log10", ti._log10_result_type, ti._log10, _LOG10_DOCSTRING, mkl_fn_to_call="_mkl_log10_to_call", mkl_impl_fn="_log10", ) _LOG1P_DOCSTRING = """ Computes the natural logarithm of (1 + `x`) for each element `x_i` of input array `x`. This function calculates `log(1 + x)` more accurately for small values of `x`. 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, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. Default: ``None``. order : {"C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. Default: ``"K"``. Returns ------- out : dpnp.ndarray An array containing the element-wise `log(1 + x)` 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.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) """ log1p = DPNPUnaryFunc( "log1p", ti._log1p_result_type, ti._log1p, _LOG1P_DOCSTRING, mkl_fn_to_call="_mkl_log1p_to_call", mkl_impl_fn="_log1p", ) _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, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. Default: ``None``. order : {"C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. Default: ``"K"``. Returns ------- out : dpnp.ndarray An array containing the element-wise 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]) """ log2 = DPNPUnaryFunc( "log2", ti._log2_result_type, ti._log2, _LOG2_DOCSTRING, mkl_fn_to_call="_mkl_log2_to_call", mkl_impl_fn="_log2", ) _LOGADDEXP_DOCSTRING = """ Calculates the natural logarithm of the sum of exponents 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, scalar} First input array, expected to have a real-valued floating-point data type. Both inputs `x1` and `x2` can not be scalars at the same time. x2 : {dpnp.ndarray, usm_ndarray, scalar} Second input array, also expected to have a real-valued floating-point data type. Both inputs `x1` and `x2` can not be scalars at the same time. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. Default: ``None``. 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 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.logaddexp2`: Logarithm of the sum of exponentiation of inputs in base-2, element-wise. :obj:`dpnp.logsumexp` : Logarithm of the sum of exponents 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) """ logaddexp = DPNPBinaryFunc( "logaddexp", ti._logaddexp_result_type, ti._logaddexp, _LOGADDEXP_DOCSTRING, ) _LOGADDEXP2_DOCSTRING = """ Calculates the logarithm of the sum of exponents in base-2 for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. This function calculates `log2(2**x1 + 2**x2)`. It is useful in machine learning when the calculated probabilities of events may be so small as to exceed the range of normal floating point numbers. In such cases the base-2 logarithm of the calculated probability can be used instead. This function allows adding probabilities stored in such a fashion. For full documentation refer to :obj:`numpy.logaddexp2`. Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} First input array, expected to have a real-valued floating-point data type. Both inputs `x1` and `x2` can not be scalars at the same time. x2 : {dpnp.ndarray, usm_ndarray, scalar} Second input array, also expected to have a real-valued floating-point data type. Both inputs `x1` and `x2` can not be scalars at the same time. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. Default: ``None``. 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 arguments `kwargs` are currently unsupported. Otherwise ``NotImplementedError`` exception will be raised. See Also -------- :obj:`dpnp.logaddexp`: Natural logarithm of the sum of exponentiation of inputs, element-wise. :obj:`dpnp.logsumexp` : Logarithm of the sum of exponentiation of the inputs. Examples -------- >>> import dpnp as np >>> prob1 = np.log2(np.array(1e-50)) >>> prob2 = np.log2(np.array(2.5e-50)) >>> prob12 = np.logaddexp2(prob1, prob2) >>> prob1, prob2, prob12 (array(-166.09640474), array(-164.77447665), array(-164.28904982)) >>> 2**prob12 array(3.5e-50) """ logaddexp2 = DPNPBinaryFunc( "logaddexp2", ufi._logaddexp2_result_type, ufi._logaddexp2, _LOGADDEXP2_DOCSTRING, )
[docs] def logsumexp(x, /, *, axis=None, dtype=None, keepdims=False, out=None): """ Calculates the logarithm of the sum of exponents of elements in the input array. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} Input array, expected to have a real-valued data type. axis : {None, int or tuple of ints}, optional Axis or axes along which values must be computed. If a tuple of unique integers, values are computed over multiple axes. If ``None``, the result is computed over the entire array. Default: ``None``. dtype : {None, dtype}, optional Data type of the returned array. If ``None``, the default data type is inferred from the "kind" of the input array data type. - If `x` has a real-valued floating-point data type, the returned array will have the same data type as `x`. - If `x` has a boolean or integral data type, the returned array will have the default floating point data type for the device where input array `x` is allocated. - If `x` has a complex-valued floating-point data type, an error is raised. If the data type (either specified or resolved) differs from the data type of `x`, the input array elements are cast to the specified data type before computing the result. Default: ``None``. keepdims : {None, bool}, optional If ``True``, the reduced axes (dimensions) are included in the result as singleton dimensions, so that the returned array remains compatible with the input arrays according to Array Broadcasting rules. Otherwise, if ``False``, the reduced axes are not included in the returned array. Default: ``False``. out : {None, dpnp.ndarray, usm_ndarray}, optional The array into which the result is written. The data type of `out` must match the expected shape and the expected data type of the result or (if provided) `dtype`. If ``None`` then a new array is returned. Default: ``None``. Returns ------- out : dpnp.ndarray An array containing the results. If the result was computed over the entire array, a zero-dimensional array is returned. The returned array has the data type as described in the `dtype` parameter description above. Note ---- This function is equivalent of `numpy.logaddexp.reduce`. See Also -------- :obj:`dpnp.log` : Natural logarithm, element-wise. :obj:`dpnp.exp` : Exponential, element-wise. :obj:`dpnp.logaddexp` : Logarithm of the sum of exponents of the inputs, element-wise. :obj:`dpnp.logaddexp2` : Logarithm of the sum of exponents of the inputs in base-2, element-wise. Examples -------- >>> import dpnp as np >>> a = np.ones(10) >>> np.logsumexp(a) array(3.30258509) >>> np.log(np.sum(np.exp(a))) array(3.30258509) """ usm_x = dpnp.get_usm_ndarray(x) return dpnp_wrap_reduction_call( usm_x, out, dpt.logsumexp, _get_accumulation_res_dt(x, dtype), axis=axis, dtype=dtype, keepdims=keepdims, )
_RAD2DEG_DOCSTRING = """ Convert angles from radians to degrees. For full documentation refer to :obj:`numpy.rad2deg`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} Angle in radians. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. Default: ``None``. order : {"C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. Default: ``"K"``. Returns ------- out : dpnp.ndarray The corresponding angle in degrees. 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.deg2rad` : Convert angles from degrees to radians. :obj:`dpnp.unwrap` : Remove large jumps in angle by wrapping. :obj:`dpnp.degrees` : Equivalent function. Notes ----- dpnp.rad2deg(x) is ``180 * x / pi``. Examples -------- >>> import dpnp as np >>> x = np.array(np.pi / 2) >>> np.rad2deg(x) array(90.) """ rad2deg = DPNPUnaryFunc( "rad2deg", ufi._degrees_result_type, ufi._degrees, _RAD2DEG_DOCSTRING, ) _RADIANS_DOCSTRING = """ Convert angles from degrees to radians. For full documentation refer to :obj:`numpy.radians`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} Input array in degrees. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. Default: ``None``. order : {"C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. Default: ``"K"``. Returns ------- out : dpnp.ndarray The corresponding radian 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.deg2rad` : Equivalent function. Examples -------- >>> import dpnp as np >>> deg = np.arange(12.) * 30. Convert a degree array to radians: >>> np.radians(deg) array([0. , 0.52359878, 1.04719755, 1.57079633, 2.0943951 , 2.61799388, 3.14159265, 3.66519143, 4.1887902 , 4.71238898, 5.23598776, 5.75958653]) >>> out = np.zeros_like(deg) >>> ret = np.radians(deg, out) >>> ret is out True """ radians = DPNPUnaryFunc( "radians", ufi._radians_result_type, ufi._radians, _RADIANS_DOCSTRING, ) _RECIPROCAL_DOCSTRING = """ Computes the reciprocal square-root for 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, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. Default: ``None``. order : {"C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. Default: ``"K"``. 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]) """ reciprocal = DPNPUnaryFunc( "reciprocal", ti._reciprocal_result_type, ti._reciprocal, _RECIPROCAL_DOCSTRING, )
[docs] def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): """ Calculates the square root of the sum of squares of elements in the input array. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} Input array, expected to have a real-valued data type. axis : {None, int or tuple of ints}, optional Axis or axes along which values must be computed. If a tuple of unique integers, values are computed over multiple axes. If ``None``, the result is computed over the entire array. Default: ``None``. dtype : {None, dtype}, optional Data type of the returned array. If ``None``, the default data type is inferred from the "kind" of the input array data type. - If `x` has a real-valued floating-point data type, the returned array will have the same data type as `x`. - If `x` has a boolean or integral data type, the returned array will have the default floating point data type for the device where input array `x` is allocated. - If `x` has a complex-valued floating-point data type, an error is raised. If the data type (either specified or resolved) differs from the data type of `x`, the input array elements are cast to the specified data type before computing the result. Default: ``None``. keepdims : {None, bool}, optional If ``True``, the reduced axes (dimensions) are included in the result as singleton dimensions, so that the returned array remains compatible with the input arrays according to Array Broadcasting rules. Otherwise, if ``False``, the reduced axes are not included in the returned array. Default: ``False``. out : {None, dpnp.ndarray, usm_ndarray}, optional The array into which the result is written. The data type of `out` must match the expected shape and the expected data type of the result or (if provided) `dtype`. If ``None`` then a new array is returned. Default: ``None``. Returns ------- out : dpnp.ndarray An array containing the results. If the result was computed over the entire array, a zero-dimensional array is returned. The returned array has the data type as described in the `dtype` parameter description above. Note ---- This function is equivalent of `numpy.hypot.reduce`. See Also -------- :obj:`dpnp.hypot` : Given the "legs" of a right triangle, return its hypotenuse. Examples -------- >>> import dpnp as np >>> a = np.ones(10) >>> np.reduce_hypot(a) array(3.16227766) >>> np.sqrt(np.sum(np.square(a))) array(3.16227766) """ usm_x = dpnp.get_usm_ndarray(x) return dpnp_wrap_reduction_call( usm_x, out, dpt.reduce_hypot, _get_accumulation_res_dt(x, dtype), axis=axis, dtype=dtype, keepdims=keepdims, )
_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. Default: ``None``. 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 reciprocal square-root. 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.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 = DPNPUnaryFunc( "rsqrt", ti._rsqrt_result_type, ti._rsqrt, _RSQRT_DOCSTRING, ) _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, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. Default: ``None``. order : {"C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. Default: ``"K"``. 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]) """ sin = DPNPUnaryFunc( "sin", ti._sin_result_type, ti._sin, _SIN_DOCSTRING, mkl_fn_to_call="_mkl_sin_to_call", mkl_impl_fn="_sin", ) _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, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. Default: ``None``. order : {"C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. Default: ``"K"``. 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]) """ sinh = DPNPUnaryFunc( "sinh", ti._sinh_result_type, ti._sinh, _SINH_DOCSTRING, mkl_fn_to_call="_mkl_sinh_to_call", mkl_impl_fn="_sinh", ) _SQRT_DOCSTRING = """ Computes the positive square-root for each element `x_i` of input array `x`. For full documentation refer to :obj:`numpy.sqrt`. 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. Default: ``None``. 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 positive square-roots 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. 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]) """ sqrt = DPNPUnaryFunc( "sqrt", ti._sqrt_result_type, ti._sqrt, _SQRT_DOCSTRING, mkl_fn_to_call="_mkl_sqrt_to_call", mkl_impl_fn="_sqrt", ) _SQUARE_DOCSTRING = """ Squares 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, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. Default: ``None``. order : {"C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. Default: ``"K"``. Returns ------- out : dpnp.ndarray An array containing the element-wise squares 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. 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]) """ square = DPNPUnaryFunc( "square", ti._square_result_type, ti._square, _SQUARE_DOCSTRING, mkl_fn_to_call="_mkl_sqr_to_call", mkl_impl_fn="_sqr", ) _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, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. Default: ``None``. order : {"C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. Default: ``"K"``. 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]) """ tan = DPNPUnaryFunc( "tan", ti._tan_result_type, ti._tan, _TAN_DOCSTRING, mkl_fn_to_call="_mkl_tan_to_call", mkl_impl_fn="_tan", ) _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, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. Default: ``None``. order : {"C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. Default: ``"K"``. 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]) """ tanh = DPNPUnaryFunc( "tanh", ti._tanh_result_type, ti._tanh, _TANH_DOCSTRING, mkl_fn_to_call="_mkl_tanh_to_call", mkl_impl_fn="_tanh", )
[docs] def unwrap(p, discont=None, axis=-1, *, period=2 * dpnp.pi): r""" Unwrap by taking the complement of large deltas with respect to the period. This unwraps a signal `p` by changing elements which have an absolute difference from their predecessor of more than ``max(discont, period / 2)`` to their `period`-complementary values. For the default case where `period` is :math:`2\pi` and `discont` is :math:`\pi`, this unwraps a radian phase `p` such that adjacent differences are never greater than :math:`\pi` by adding :math:`2k\pi` for some integer :math:`k`. For full documentation refer to :obj:`numpy.unwrap`. Parameters ---------- p : {dpnp.ndarray, usm_ndarray} Input array. discont : {float, None}, optional Maximum discontinuity between values, default is ``None`` which is an alias for ``period / 2``. Values below ``period / 2`` are treated as if they were ``period / 2``. To have an effect different from the default, `discont` should be larger than ``period / 2``. Default: ``None``. axis : int, optional Axis along which unwrap will operate, default is the last axis. Default: ``-1``. period : float, optional Size of the range over which the input wraps. Default: ``2 * pi``. Returns ------- out : dpnp.ndarray Output array. See Also -------- :obj:`dpnp.rad2deg` : Convert angles from radians to degrees. :obj:`dpnp.deg2rad` : Convert angles from degrees to radians. Notes ----- If the discontinuity in `p` is smaller than ``period / 2``, but larger than `discont`, no unwrapping is done because taking the complement would only make the discontinuity larger. Examples -------- >>> import dpnp as np >>> phase = np.linspace(0, np.pi, num=5) >>> phase[3:] += np.pi >>> phase array([0. , 0.78539816, 1.57079633, 5.49778714, 6.28318531]) >>> np.unwrap(phase) array([ 0. , 0.78539816, 1.57079633, -0.78539816, 0. ]) >>> phase = np.array([0, 1, 2, -1, 0]) >>> np.unwrap(phase, period=4) array([0, 1, 2, 3, 4]) >>> phase = np.array([1, 2, 3, 4, 5, 6, 1, 2, 3]) >>> np.unwrap(phase, period=6) array([1, 2, 3, 4, 5, 6, 7, 8, 9]) >>> phase = np.array([2, 3, 4, 5, 2, 3, 4, 5]) >>> np.unwrap(phase, period=4) array([2, 3, 4, 5, 6, 7, 8, 9]) >>> phase_deg = np.mod(np.linspace(0 ,720, 19), 360) - 180 >>> np.unwrap(phase_deg, period=360) array([-180., -140., -100., -60., -20., 20., 60., 100., 140., 180., 220., 260., 300., 340., 380., 420., 460., 500., 540.]) """ dpnp.check_supported_arrays_type(p) p_nd = p.ndim p_diff = dpnp.diff(p, axis=axis) if discont is None: discont = period / 2 # full slices slice1 = [slice(None, None)] * p_nd slice1[axis] = slice(1, None) slice1 = tuple(slice1) dt = dpnp.result_type(p_diff, period) if dpnp.issubdtype(dt, dpnp.integer): interval_high, rem = divmod(period, 2) boundary_ambiguous = rem == 0 else: interval_high = period / 2 boundary_ambiguous = True interval_low = -interval_high ddmod = p_diff - interval_low ddmod = dpnp.remainder(ddmod, period, out=ddmod) ddmod += interval_low if boundary_ambiguous: mask = ddmod == interval_low mask &= p_diff > 0 ddmod = dpnp.where(mask, interval_high, ddmod, out=ddmod) ph_correct = dpnp.subtract(ddmod, p_diff, out=ddmod) abs_p_diff = dpnp.abs(p_diff, out=p_diff) ph_correct = dpnp.where(abs_p_diff < discont, 0, ph_correct, out=ph_correct) up = dpnp.astype(p, dtype=dt, copy=True) up[slice1] = p[slice1] # TODO: replace, once dpctl-1757 resolved # up[slice1] += ph_correct.cumsum(axis=axis) up[slice1] += ph_correct.cumsum(axis=axis, dtype=dt) return up