diff --git a/.github/workflows/check-mkl-interfaces.yaml b/.github/workflows/check-mkl-interfaces.yaml index fb294e7c4929..3d89716c6630 100644 --- a/.github/workflows/check-mkl-interfaces.yaml +++ b/.github/workflows/check-mkl-interfaces.yaml @@ -229,7 +229,7 @@ jobs: python -c "import dpnp; print(dpnp.__version__)" - name: Run tests - if: env.rerun-tests-on-failure == 'true' + if: env.rerun-tests-on-failure != 'true' run: | python -m pytest -ra --pyargs dpnp.tests env: diff --git a/dpnp/dpnp_iface_bitwise.py b/dpnp/dpnp_iface_bitwise.py index 0cfd8e6fcade..bbc9e465f20d 100644 --- a/dpnp/dpnp_iface_bitwise.py +++ b/dpnp/dpnp_iface_bitwise.py @@ -130,21 +130,17 @@ def binary_repr(num, width=None): _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`. +element :math:`x1_i` of the input array `x1` with the respective element +:math:`x2_i` of the input array `x2`. For full documentation refer to :obj:`numpy.bitwise_and`. Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have integer or boolean data type. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, expected to have an integer or boolean data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have integer or boolean data - type. Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also expected to have an integer or boolean data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -175,6 +171,13 @@ def binary_repr(num, width=None): :obj:`dpnp.binary_repr` : Return the binary representation of the input number as a string. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -206,6 +209,7 @@ def binary_repr(num, width=None): '1100' >>> np.bitwise_and(np.array([14, 3]), 13) array([12, 1]) + """ bitwise_and = DPNPBinaryFunc( @@ -225,7 +229,7 @@ def binary_repr(num, width=None): Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have integer or boolean data type. + Input array, expected to have an integer data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -272,21 +276,17 @@ def binary_repr(num, width=None): _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`. +element :math:`x1_i` of the input array `x1` with the respective element +:math:`x2_i` of the input array `x2`. For full documentation refer to :obj:`numpy.bitwise_or`. Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have integer or boolean data type. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, expected to have an integer or boolean data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have integer or boolean data - type. Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also expected to have an integer or boolean data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -317,6 +317,13 @@ def binary_repr(num, width=None): :obj:`dpnp.binary_repr` : Return the binary representation of the input number as a string. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -339,6 +346,7 @@ def binary_repr(num, width=None): array(29) >>> np.binary_repr(29) '11101' + """ bitwise_or = DPNPBinaryFunc( @@ -352,21 +360,17 @@ def binary_repr(num, width=None): _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`. +element :math:`x1_i` of the input array `x1` with the respective element +:math:`x2_i` of the input array `x2`. For full documentation refer to :obj:`numpy.bitwise_xor`. Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have integer or boolean data type. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, expected to have an integer or boolean data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have integer or boolean data - type. Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also expected to have an integer or boolean data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -397,6 +401,13 @@ def binary_repr(num, width=None): :obj:`dpnp.binary_repr` : Return the binary representation of the input number as a string. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -423,6 +434,7 @@ def binary_repr(num, width=None): array(28) >>> np.binary_repr(28) '11100' + """ bitwise_xor = DPNPBinaryFunc( @@ -435,7 +447,7 @@ def binary_repr(num, width=None): _INVERT_DOCSTRING = """ -Inverts (flips) each bit for each element `x_i` of the input array `x`. +Inverts (flips) each bit for each element :math:`x_i` of the input array `x`. Note that :obj:`dpnp.bitwise_invert` is an alias of :obj:`dpnp.invert`. @@ -444,7 +456,7 @@ def binary_repr(num, width=None): Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have integer or boolean data type. + Input array, expected to have an integer or boolean data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -514,9 +526,9 @@ def binary_repr(num, width=None): bitwise_invert = invert # bitwise_invert is an alias for invert _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`. +Shifts the bits of each element :math:`x1_i` of the input array `x1` to the +left by appending :math:`x2_i` (i.e., the respective element in the input array +`x2`) zeros to the right of :math:`x1_i`. Note that :obj:`dpnp.bitwise_left_shift` is an alias of :obj:`dpnp.left_shift`. @@ -525,14 +537,10 @@ def binary_repr(num, width=None): Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have integer data type. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, expected to have an integer data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have integer data type. + Second input array, also expected to have an integer data type. Each element must be greater than or equal to ``0``. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -560,6 +568,13 @@ def binary_repr(num, width=None): :obj:`dpnp.binary_repr` : Return the binary representation of the input number as a string. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -580,6 +595,7 @@ def binary_repr(num, width=None): array(20) >>> np.binary_repr(20) '10100' + """ left_shift = DPNPBinaryFunc( @@ -594,8 +610,8 @@ def binary_repr(num, width=None): _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`. +Shifts the bits of each element :math:`x1_i` of the input array `x1` to the +right according to the respective element :math:`x2_i` of the input array `x2`. Note that :obj:`dpnp.bitwise_right_shift` is an alias of :obj:`dpnp.right_shift`. @@ -604,14 +620,10 @@ def binary_repr(num, width=None): Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have integer data type. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, expected to have an integer data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have integer data type. + Second input array, also expected to have an integer data type. Each element must be greater than or equal to ``0``. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -640,6 +652,13 @@ def binary_repr(num, width=None): :obj:`dpnp.binary_repr` : Return the binary representation of the input number as a string. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -660,6 +679,7 @@ def binary_repr(num, width=None): array(5) >>> np.binary_repr(5) '101' + """ right_shift = DPNPBinaryFunc( diff --git a/dpnp/dpnp_iface_linearalgebra.py b/dpnp/dpnp_iface_linearalgebra.py index c881edfd4c35..fa2cb6136d67 100644 --- a/dpnp/dpnp_iface_linearalgebra.py +++ b/dpnp/dpnp_iface_linearalgebra.py @@ -617,7 +617,7 @@ def inner(a, b): See Also -------- - :obj:`dpnp.einsum` : Einstein summation convention.. + :obj:`dpnp.einsum` : Einstein summation convention. :obj:`dpnp.dot` : Generalized matrix product, using second last dimension of `b`. :obj:`dpnp.tensordot` : Sum products over arbitrary axes. @@ -998,7 +998,7 @@ def matvec( See Also -------- - :obj:`dpnp.vecdot` : Vector-vector product.. + :obj:`dpnp.vecdot` : Vector-vector product. :obj:`dpnp.vecmat` : Vector-matrix product. :obj:`dpnp.matmul` : Matrix-matrix product. :obj:`dpnp.einsum` : Einstein summation convention. @@ -1502,7 +1502,7 @@ def vecmat( See Also -------- - :obj:`dpnp.vecdot` : Vector-vector product.. + :obj:`dpnp.vecdot` : Vector-vector product. :obj:`dpnp.matvec` : Matrix-vector product. :obj:`dpnp.matmul` : Matrix-matrix product. :obj:`dpnp.einsum` : Einstein summation convention. diff --git a/dpnp/dpnp_iface_logic.py b/dpnp/dpnp_iface_logic.py index 62d581ef9d63..84258f698b8f 100644 --- a/dpnp/dpnp_iface_logic.py +++ b/dpnp/dpnp_iface_logic.py @@ -84,7 +84,7 @@ def all(a, /, axis=None, out=None, keepdims=False, *, where=True): """ - Test whether all array elements along a given axis evaluate to True. + Test whether all array elements along a given axis evaluate to ``True``. For full documentation refer to :obj:`numpy.all`. @@ -129,9 +129,9 @@ def all(a, /, axis=None, out=None, keepdims=False, *, where=True): See Also -------- - :obj:`dpnp.ndarray.all` : equivalent method + :obj:`dpnp.ndarray.all` : Equivalent method. :obj:`dpnp.any` : Test whether any element along a given axis evaluates - to True. + to ``True``. Notes ----- @@ -195,11 +195,9 @@ def allclose(a, b, rtol=1.0e-5, atol=1.0e-8, equal_nan=False): Parameters ---------- a : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have numeric data type. - Both inputs `a` and `b` can not be scalars at the same time. + First input array, expected to have a numeric data type. b : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have numeric data type. - Both inputs `a` and `b` can not be scalars at the same time. + Second input array, also expected to have a numeric data type. rtol : {dpnp.ndarray, usm_ndarray, scalar}, optional The relative tolerance parameter. @@ -229,6 +227,8 @@ def allclose(a, b, rtol=1.0e-5, atol=1.0e-8, equal_nan=False): Notes ----- + At least one of `x1` or `x2` must be an array. + The comparison of `a` and `b` uses standard broadcasting, which means that `a` and `b` need not have the same shape in order for ``dpnp.allclose(a, b)`` to evaluate to ``True``. @@ -261,7 +261,7 @@ def allclose(a, b, rtol=1.0e-5, atol=1.0e-8, equal_nan=False): def any(a, /, axis=None, out=None, keepdims=False, *, where=True): """ - Test whether any array element along a given axis evaluates to True. + Test whether any array element along a given axis evaluates to ``True``. For full documentation refer to :obj:`numpy.any`. @@ -306,9 +306,9 @@ def any(a, /, axis=None, out=None, keepdims=False, *, where=True): See Also -------- - :obj:`dpnp.ndarray.any` : equivalent method + :obj:`dpnp.ndarray.any` : Equivalent method. :obj:`dpnp.all` : Test whether all elements along a given axis evaluate - to True. + to ``True``. Notes ----- @@ -365,10 +365,8 @@ def array_equal(a1, a2, equal_nan=False): ---------- a1 : {dpnp.ndarray, usm_ndarray, scalar} First input array. - Both inputs `x1` and `x2` can not be scalars at the same time. a2 : {dpnp.ndarray, usm_ndarray, scalar} Second input array. - Both inputs `x1` and `x2` can not be scalars at the same time. equal_nan : bool, optional Whether to compare ``NaNs`` as equal. If the dtype of `a1` and `a2` is complex, values will be considered equal if either the real or the @@ -388,6 +386,10 @@ def array_equal(a1, a2, equal_nan=False): :obj:`dpnp.array_equiv`: Returns ``True`` if input arrays are shape consistent and all elements equal. + Notes + ----- + At least one of `x1` or `x2` must be an array. + Examples -------- >>> import dpnp as np @@ -490,10 +492,8 @@ def array_equiv(a1, a2): ---------- a1 : {dpnp.ndarray, usm_ndarray, scalar} First input array. - Both inputs `x1` and `x2` can not be scalars at the same time. a2 : {dpnp.ndarray, usm_ndarray, scalar} Second input array. - Both inputs `x1` and `x2` can not be scalars at the same time. Returns ------- @@ -501,6 +501,10 @@ def array_equiv(a1, a2): A 0-d array with ``True`` value if the arrays are equivalent, ``False`` otherwise. + Notes + ----- + At least one of `x1` or `x2` must be an array. + Examples -------- >>> import dpnp as np @@ -540,21 +544,17 @@ def array_equiv(a1, a2): _EQUAL_DOCSTRING = """ -Calculates equality test results for each element `x1_i` of the input array `x1` -with the respective element `x2_i` of the input array `x2`. +Calculates equality test results for each element :math:`x1_i` of the input +array `x1` with the respective element :math:`x2_i` of the input array `x2`. For full documentation refer to :obj:`numpy.equal`. Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, may have any data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also may have any data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array have the correct shape and the expected data type. @@ -583,6 +583,13 @@ def array_equiv(a1, a2): :obj:`dpnp.greater` : Return the truth value of (x1 > x2) element-wise. :obj:`dpnp.less` : Return the truth value of (x1 < x2) element-wise. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -616,21 +623,18 @@ def array_equiv(a1, a2): _GREATER_DOCSTRING = """ -Computes the greater-than test results for each element `x1_i` of -the input array `x1` with the respective element `x2_i` of the input array `x2`. +Computes the greater-than test results for each element :math:`x1_i` of the +input array `x1` with the respective element :math:`x2_i` of the input array +`x2`. For full documentation refer to :obj:`numpy.greater`. Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, may have any data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also may have any data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -659,6 +663,13 @@ def array_equiv(a1, a2): :obj:`dpnp.equal` : Return (x1 == x2) element-wise. :obj:`dpnp.not_equal` : Return (x1 != x2) element-wise. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -686,21 +697,18 @@ def array_equiv(a1, a2): _GREATER_EQUAL_DOCSTRING = """ -Computes the greater-than or equal-to test results for each element `x1_i` of -the input array `x1` with the respective element `x2_i` of the input array `x2`. +Computes the greater-than or equal-to test results for each element :math:`x1_i` +of the input array `x1` with the respective element :math:`x2_i` of the input +array `x2`. For full documentation refer to :obj:`numpy.greater_equal`. Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, may have any data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also may have any data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -730,6 +738,13 @@ def array_equiv(a1, a2): :obj:`dpnp.equal` : Return (x1 == x2) element-wise. :obj:`dpnp.not_equal` : Return (x1 != x2) element-wise. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -749,7 +764,7 @@ def array_equiv(a1, a2): """ greater_equal = DPNPBinaryFunc( - "greater", + "greater_equal", ti._greater_equal_result_type, ti._greater_equal, _GREATER_EQUAL_DOCSTRING, @@ -775,11 +790,9 @@ def isclose(a, b, rtol=1e-05, atol=1e-08, equal_nan=False): Parameters ---------- a : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have numeric data type. - Both inputs `a` and `b` can not be scalars at the same time. + First input array, expected to have a numeric data type. b : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have numeric data type. - Both inputs `a` and `b` can not be scalars at the same time. + Second input array, also expected to have a numeric data type. rtol : {dpnp.ndarray, usm_ndarray, scalar}, optional The relative tolerance parameter. @@ -805,6 +818,10 @@ def isclose(a, b, rtol=1e-05, atol=1e-08, equal_nan=False): :obj:`dpnp.allclose` : Returns ``True`` if two arrays are element-wise equal within a tolerance. + Notes + ----- + At least one of `x1` or `x2` must be an array. + Examples -------- >>> import dpnp as np @@ -968,14 +985,14 @@ def iscomplexobj(x): _ISFINITE_DOCSTRING = """ -Test if each element of input array is a finite number. +Test each element :math:`x_i` of the input array `x` to determine if finite. For full documentation refer to :obj:`numpy.isfinite`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + Input array, may have any data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -1099,14 +1116,15 @@ def isfortran(a): _ISINF_DOCSTRING = """ -Test if each element of input array is an infinity. +Tests each element :math:`x_i` of the input array `x` to determine if equal to +positive or negative infinity. For full documentation refer to :obj:`numpy.isinf`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + Input array, may have any data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -1156,14 +1174,15 @@ def isfortran(a): _ISNAN_DOCSTRING = """ -Test if each element of an input array is a NaN. +Tests each element :math:`x_i` of the input array `x` to determine whether the +element is ``NaN``. For full documentation refer to :obj:`numpy.isnan`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + Input array, may have any data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -1490,21 +1509,17 @@ def isscalar(element): _LESS_DOCSTRING = """ -Computes the less-than test results for each element `x1_i` of -the input array `x1` with the respective element `x2_i` of the input array `x2`. +Computes the less-than test results for each element :math:`x1_i` of the input +array `x1` with the respective element :math:`x2_i` of the input array `x2`. For full documentation refer to :obj:`numpy.less`. Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, may have any data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also may have any data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -1533,6 +1548,13 @@ def isscalar(element): :obj:`dpnp.equal` : Return (x1 == x2) element-wise. :obj:`dpnp.not_equal` : Return (x1 != x2) element-wise. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -1560,21 +1582,18 @@ def isscalar(element): _LESS_EQUAL_DOCSTRING = """ -Computes the less-than or equal-to test results for each element `x1_i` of -the input array `x1` with the respective element `x2_i` of the input array `x2`. +Computes the less-than or equal-to test results for each element :math:`x1_i` +of the input array `x1` with the respective element :math:`x2_i` of the input +array `x2`. For full documentation refer to :obj:`numpy.less_equal`. Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, may have any data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also may have any data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -1603,6 +1622,13 @@ def isscalar(element): :obj:`dpnp.equal` : Return (x1 == x2) element-wise. :obj:`dpnp.not_equal` : Return (x1 != x2) element-wise. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -1630,21 +1656,17 @@ def isscalar(element): _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`. +Computes the logical AND for each element :math:`x1_i` of the input array `x1` +with the respective element :math:`x2_i` of the input array `x2`. For full documentation refer to :obj:`numpy.logical_and`. Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, may have any data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also may have any data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -1672,6 +1694,13 @@ def isscalar(element): :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. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -1703,14 +1732,14 @@ def isscalar(element): _LOGICAL_NOT_DOCSTRING = """ -Computes the logical NOT for each element `x_i` of input array `x`. +Computes the logical NOT for each element :math:`x_i` of input array `x`. For full documentation refer to :obj:`numpy.logical_not`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array. + Input array, may have any data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -1737,6 +1766,13 @@ def isscalar(element): :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. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -1759,21 +1795,17 @@ def isscalar(element): _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`. +Computes the logical OR for each element :math:`x1_i` of the input array `x1` +with the respective element :math:`x2_i` of the input array `x2`. For full documentation refer to :obj:`numpy.logical_or`. Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, may have any data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also may have any data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -1801,6 +1833,13 @@ def isscalar(element): :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. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -1832,21 +1871,17 @@ def isscalar(element): _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`. +Computes the logical XOR for each element :math:`x1_i` of the input array `x1` +with the respective element :math:`x2_i` of the input array `x2`. For full documentation refer to :obj:`numpy.logical_xor`. Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, may have any data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also may have any data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -1874,6 +1909,13 @@ def isscalar(element): :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. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -1903,21 +1945,17 @@ def isscalar(element): _NOT_EQUAL_DOCSTRING = """ -Calculates inequality test results for each element `x1_i` of the -input array `x1` with the respective element `x2_i` of the input array `x2`. +Calculates inequality test results for each element :math:`x1_i` of the input +array `x1` with the respective element :math:`x2_i` of the input array `x2`. For full documentation refer to :obj:`numpy.not_equal`. Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, may have any data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also may have any data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -1946,6 +1984,13 @@ def isscalar(element): :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. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np diff --git a/dpnp/dpnp_iface_mathematical.py b/dpnp/dpnp_iface_mathematical.py index 9c9a8049a14c..3613c9bffff6 100644 --- a/dpnp/dpnp_iface_mathematical.py +++ b/dpnp/dpnp_iface_mathematical.py @@ -349,14 +349,14 @@ def _process_ediff1d_args(arg, arg_name, ary_dtype, ary_sycl_queue, usm_type): _ABS_DOCSTRING = """ -Calculates the absolute value for each element `x_i` of input array `x`. +Calculates the absolute value for each element :math:`x_i` of input array `x`. For full documentation refer to :obj:`numpy.absolute`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + Input array, may have any data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -389,21 +389,22 @@ def _process_ediff1d_args(arg, arg_name, ary_dtype, ary_sycl_queue, usm_type): Notes ----- -``dpnp.abs`` is a shorthand for this function. +``dpnp.absolute`` is an equivalent function. Examples -------- >>> import dpnp as np >>> a = np.array([-1.2, 1.2]) ->>> np.absolute(a) +>>> np.abs(a) array([1.2, 1.2]) >>> a = np.array(1.2 + 1j) ->>> np.absolute(a) +>>> np.abs(a) array(1.5620499351813308) + """ -absolute = DPNPUnaryFunc( +abs = DPNPUnaryFunc( "abs", ti._abs_result_type, ti._abs, @@ -413,25 +414,21 @@ def _process_ediff1d_args(arg, arg_name, ary_dtype, ary_sycl_queue, usm_type): ) -abs = absolute +absolute = abs _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`. +Calculates the sum for each element :math:`x1_i` of the input array `x1` with +the respective element :math:`x2_i` of the input array `x2`. For full documentation refer to :obj:`numpy.add`. Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, may have any data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also may have any data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -456,7 +453,12 @@ def _process_ediff1d_args(arg, arg_name, ary_dtype, ary_sycl_queue, usm_type): Notes ----- -Equivalent to `x1` + `x2` in terms of array broadcasting. +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + +Equivalent to :math:`x1 + x2` in terms of array broadcasting. Examples -------- @@ -480,6 +482,7 @@ def _process_ediff1d_args(arg, arg_name, ary_dtype, ary_sycl_queue, usm_type): array([[ 0., 2., 4.], [ 3., 5., 7.], [ 6., 8., 10.]]) + """ @@ -494,16 +497,16 @@ def _process_ediff1d_args(arg, arg_name, ary_dtype, ary_sycl_queue, usm_type): ) -_ANGLE_DOCSTRING = """ -Computes the phase angle (also called the argument) of each element `x_i` for -input array `x`. +_ANGLE_DOCSTRING = r""" +Computes the phase angle (also called the argument) of each element :math:`x_i` +for input array `x`. For full documentation refer to :obj:`numpy.angle`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have a complex-valued floating-point data type. + Input array, expected to have a complex floating-point data type. deg : bool, optional Return angle in degrees if ``True``, radians if ``False``. @@ -527,17 +530,19 @@ def _process_ediff1d_args(arg, arg_name, ary_dtype, ary_sycl_queue, usm_type): Notes ----- -Although the angle of the complex number 0 is undefined, `dpnp.angle(0)` returns the value 0. +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. +:obj:`dpnp.atan2` : Element-wise arc tangent of :math:`\frac{x1}{x2}` choosing + the quadrant correctly. +:obj:`dpnp.atan` : Trigonometric inverse tangent, element-wise. +:obj:`dpnp.abs` : Calculate the absolute value element-wise. :obj:`dpnp.real` : Return the real part of the complex argument. :obj:`dpnp.imag` : Return the imaginary part of the complex argument. :obj:`dpnp.real_if_close` : Return the real part of the input is complex - with all imaginary parts close to zero. + with all imaginary parts close to zero. Examples -------- @@ -548,6 +553,7 @@ def _process_ediff1d_args(arg, arg_name, ary_dtype, ary_sycl_queue, usm_type): >>> np.angle(a, deg=True) # in degrees array([ 0., 90., 45.]) + """ angle = DPNPAngle( @@ -567,7 +573,7 @@ def around(x, /, decimals=0, out=None): Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + Input array, expected to have a numeric data type. decimals : int, optional Number of decimal places to round to. If `decimals` is negative, it specifies the number of positions to the left of the decimal point. @@ -604,7 +610,10 @@ def around(x, /, decimals=0, out=None): _CEIL_DOCSTRING = """ -Returns the ceiling for each element `x_i` for input array `x`. +Returns the ceiling for each element :math:`x_i` for input array `x`. +Rounds each element :math:`x_i` of the input array `x` to the smallest (i.e., +closest to ``-infinity``) integer-valued number that is not less than +:math:`x_i`. For full documentation refer to :obj:`numpy.ceil`. @@ -646,6 +655,7 @@ def around(x, /, decimals=0, out=None): >>> 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 = DPNPUnaryFunc( @@ -740,14 +750,15 @@ def clip(a, /, min=None, max=None, *, out=None, order="K", **kwargs): _CONJ_DOCSTRING = """ -Computes conjugate of each element `x_i` for input array `x`. +Returns the complex conjugate for each element :math:`x_i` of the 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. + Input array, may have any data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -771,16 +782,16 @@ def clip(a, /, min=None, max=None, *, out=None, order="K", **kwargs): Examples -------- >>> import dpnp as np ->>> np.conjugate(np.array(1+2j)) +>>> np.conj(np.array(1+2j)) (1-2j) >>> x = np.eye(2) + 1j * np.eye(2) ->>> np.conjugate(x) +>>> np.conj(x) array([[ 1.-1.j, 0.-0.j], [ 0.-0.j, 1.-1.j]]) """ -conjugate = DPNPUnaryFunc( +conj = DPNPUnaryFunc( "conj", ti._conj_result_type, ti._conj, @@ -789,26 +800,22 @@ def clip(a, /, min=None, max=None, *, out=None, order="K", **kwargs): mkl_impl_fn="_conj", ) -conj = conjugate +conjugate = conj _COPYSIGN_DOCSTRING = """ -Composes a floating-point value with the magnitude of `x1_i` and the sign of -`x2_i` for each element of input arrays `x1` and `x2`. +Composes a floating-point value with the magnitude of :math:`x1_i` and the sign +of :math:`x2_i` for each element of the input array `x1`. For full documentation refer to :obj:`numpy.copysign`. Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have a real floating-point data type. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, expected to have a real-valued floating-point data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have a real floating-point data + 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. @@ -836,6 +843,13 @@ def clip(a, /, min=None, max=None, *, out=None, order="K", **kwargs): :obj:`dpnp.negative` : Return the numerical negative of each element of `x`. :obj:`dpnp.positive` : Return the numerical positive of each element of `x`. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -1252,10 +1266,11 @@ def cumulative_prod( be cast if necessary. Default: ``None``. - include_initial : bool, optional - Boolean indicating whether to include the initial value (ones) as - the first value in the output. With ``include_initial=True`` - the shape of the output is different than the shape of the input. + include_initial : {None, bool}, optional + A boolean indicating whether to include the initial value (one) as + the first value along the provided axis in the output. With + ``include_initial=True`` the shape of the output is different than + the shape of the input. Default: ``False``. @@ -1341,10 +1356,11 @@ def cumulative_sum( be cast if necessary. Default: ``None``. - include_initial : bool, optional - Boolean indicating whether to include the initial value (ones) as - the first value in the output. With ``include_initial=True`` - the shape of the output is different than the shape of the input. + include_initial : {None, bool}, optional + A boolean indicating whether to include the initial value (zero) as + the first value along the provided axis in the output. With + ``include_initial=True`` the shape of the output is different than + the shape of the input. Default: ``False``. @@ -1475,22 +1491,18 @@ def diff(a, n=1, axis=-1, prepend=None, append=None): return dpnp_array._create_from_usm_ndarray(usm_res) -_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`. +_DIVIDE_DOCSTRING = r""" +Calculates the ratio for each element :math:`x1_i` of the input array `x1` with +the respective element :math:`x2_i` of the input array `x2`. For full documentation refer to :obj:`numpy.divide`. Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, expected to have a floating-point data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also 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. @@ -1515,10 +1527,14 @@ def diff(a, n=1, axis=-1, prepend=None, append=None): Notes ----- -Equivalent to `x1` / `x2` in terms of array-broadcasting. +At least one of `x1` or `x2` must be an array. -The ``true_divide(x1, x2)`` function is an alias for -``divide(x1, x2)``. +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + +Equivalent to :math:`\frac{x1}{x2}` in terms of array-broadcasting. + +The ``true_divide(x1, x2)`` function is an alias for ``divide(x1, x2)``. Examples -------- @@ -1542,6 +1558,7 @@ def diff(a, n=1, axis=-1, prepend=None, append=None): array([[0. , 0.5, 1. ], [1.5, 2. , 2.5], [3. , 3.5, 4. ]]) + """ divide = DPNPBinaryFunc( @@ -1695,6 +1712,7 @@ def ediff1d(ary, to_end=None, to_begin=None): >>> a = np.array([-1.2, 1.2]) >>> np.fabs(a) array([1.2, 1.2]) + """ fabs = DPNPUnaryFunc( @@ -1756,6 +1774,7 @@ def ediff1d(ary, to_end=None, to_begin=None): >>> a = np.array([2.1, 2.9, -2.1, -2.9]) >>> np.fix(a) array([ 2., 2., -2., -2.]) + """ fix = DPNPFix( @@ -1767,8 +1786,9 @@ def ediff1d(ary, to_end=None, to_begin=None): _FLOAT_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`. +Calculates :math:`x1_i` raised to :math:`x2_i` for each element :math:`x1_i` of +the input array `x1` with the respective element :math:`x2_i` of the input +array `x2`. This differs from the power function in that boolean, integers, and float16 are promoted to floats with a minimum precision of float32 so that the result is @@ -1784,13 +1804,9 @@ def ediff1d(ary, to_end=None, to_begin=None): Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have floating-point data types. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, expected to have a numeric data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to floating-point data types. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also expected to a 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. @@ -1817,6 +1833,13 @@ def ediff1d(ary, to_end=None, to_begin=None): -------- :obj:`dpnp.power` : Power function that preserves type. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -1856,6 +1879,7 @@ def ediff1d(ary, to_end=None, to_begin=None): >>> np.float_power(x3, 1.5, dtype=np.complex64) array([1.1924881e-08-1.j, 9.5399045e-08-8.j], dtype=complex64) + """ float_power = DPNPBinaryFunc( @@ -1870,9 +1894,9 @@ def ediff1d(ary, to_end=None, to_begin=None): _FLOOR_DOCSTRING = """ -Returns the floor for each element `x_i` for input array `x`. +Returns the floor for each element :math:`x_i` for input array `x`. -The floor of `x_i` is the largest integer `n`, such that `n <= x_i`. +The floor of :math:`x_i` is the largest integer `n`, such that `n <= x_i`. For full documentation refer to :obj:`numpy.floor`. @@ -1921,6 +1945,7 @@ def ediff1d(ary, to_end=None, to_begin=None): >>> 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]) + """ floor = DPNPUnaryFunc( @@ -1934,22 +1959,19 @@ def ediff1d(ary, to_end=None, to_begin=None): _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. +Rounds the result of dividing each element :math:`x1_i` of the input array `x1` +by the respective element :math:`x2_i` of the input array `x2` to the greatest +(i.e., closest to ``+infinity``) 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, scalar} - First input array, expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, expected to have a real-valued data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also 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. @@ -1980,6 +2002,13 @@ def ediff1d(ary, to_end=None, to_begin=None): :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. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -1995,6 +2024,7 @@ def ediff1d(ary, to_end=None, to_begin=None): >>> x1 = np.array([1., 2., 3., 4.]) >>> x1 // 2.5 array([0., 0., 1., 1.]) + """ floor_divide = DPNPBinaryFunc( @@ -2010,7 +2040,7 @@ def ediff1d(ary, to_end=None, to_begin=None): Compares two input arrays `x1` and `x2` and returns a new array containing the element-wise maxima. -If one of the elements being compared is a NaN, then the non-NaN element is +If one of the elements being compared is a ``NaN``, then the non-NaN element is returned. If both elements are NaNs then the first is returned. The latter distinction is important for complex NaNs, which are defined as at least one of the real or imaginary parts being a NaN. The net effect is that NaNs are @@ -2021,13 +2051,9 @@ def ediff1d(ary, to_end=None, to_begin=None): Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, may have any data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also may have any data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -2062,6 +2088,11 @@ def ediff1d(ary, to_end=None, to_begin=None): Notes ----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + ``fmax(x1, x2)`` is equivalent to ``dpnp.where(x1 >= x2, x1, x2)`` when neither `x1` nor `x2` are NaNs, but it is faster and does proper broadcasting. @@ -2083,6 +2114,7 @@ def ediff1d(ary, to_end=None, to_begin=None): >>> x2 = np.array([0, np.nan, np.nan]) >>> np.fmax(x1, x2) array([ 0., 0., nan]) + """ fmax = DPNPBinaryFunc( @@ -2099,7 +2131,7 @@ def ediff1d(ary, to_end=None, to_begin=None): Compares two input arrays `x1` and `x2` and returns a new array containing the element-wise minima. -If one of the elements being compared is a NaN, then the non-NaN element is +If one of the elements being compared is a ``NaN``, then the non-NaN element is returned. If both elements are NaNs then the first is returned. The latter distinction is important for complex NaNs, which are defined as at least one of the real or imaginary parts being a NaN. The net effect is that NaNs are @@ -2110,13 +2142,9 @@ def ediff1d(ary, to_end=None, to_begin=None): Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, may have any data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also may have any data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -2151,6 +2179,11 @@ def ediff1d(ary, to_end=None, to_begin=None): Notes ----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + ``fmin(x1, x2)`` is equivalent to ``dpnp.where(x1 <= x2, x1, x2)`` when neither `x1` nor `x2` are NaNs, but it is faster and does proper broadcasting. @@ -2172,6 +2205,7 @@ def ediff1d(ary, to_end=None, to_begin=None): >>> x2 = np.array([0, np.nan, np.nan]) >>> np.fmin(x1, x2) array([ 0., 0., nan]) + """ fmin = DPNPBinaryFunc( @@ -2185,8 +2219,8 @@ def ediff1d(ary, to_end=None, to_begin=None): _FMOD_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`. +Calculates the remainder of division for each element :math:`x1_i` of the input array +`x1` with the respective element :math:`x2_i` of the input array `x2`. This function is equivalent to the Matlab(TM) ``rem`` function and should not be confused with the Python modulus operator ``x1 % x2``. @@ -2196,13 +2230,10 @@ def ediff1d(ary, to_end=None, to_begin=None): 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. + First input array, expected to have a boolean or real-valued data type. 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). + Second input array, also expected to have a boolean or 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. @@ -2230,6 +2261,13 @@ def ediff1d(ary, to_end=None, to_begin=None): :obj:`dpnp.remainder` : Equivalent to the Python ``%`` operator. :obj:`dpnp.divide` : Standard division. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -2250,6 +2288,7 @@ def ediff1d(ary, to_end=None, to_begin=None): array([[-1, 0], [-1, 0], [ 1, 0]]) + """ fmod = DPNPBinaryFunc( @@ -2261,8 +2300,8 @@ def ediff1d(ary, to_end=None, to_begin=None): mkl_impl_fn="_fmod", ) -_GCD_DOCSTRING = """ -Returns the greatest common divisor of ``|x1|`` and ``|x2|``. +_GCD_DOCSTRING = r""" +Returns the greatest common divisor of :math:`\abs{x1}` and :math:`\abs{x2}`. For full documentation refer to :obj:`numpy.gcd`. @@ -2270,12 +2309,8 @@ def ediff1d(ary, to_end=None, to_begin=None): ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} First input array, expected to have an integer 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 an integer data type. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -2301,6 +2336,13 @@ def ediff1d(ary, to_end=None, to_begin=None): -------- :obj:`dpnp.lcm` : The lowest common multiple. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -2308,6 +2350,7 @@ def ediff1d(ary, to_end=None, to_begin=None): array(4) >>> np.gcd(np.arange(6), 20) array([20, 1, 2, 1, 4, 5]) + """ gcd = DPNPBinaryFunc( @@ -2538,13 +2581,10 @@ def gradient(f, *varargs, axis=None, edge_order=1): Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - Input values. - Both inputs `x1` and `x2` can not be scalars at the same time. + Input values, expected to have a real-valued floating-point data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - The value of the function when `x1` is ``0``. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + The value of the function when `x1` is ``0``, also 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. @@ -2566,6 +2606,13 @@ def gradient(f, *varargs, axis=None, edge_order=1): Keyword argument `kwargs` is currently unsupported. Otherwise ``NotImplementedError`` exception will be raised. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -2574,6 +2621,7 @@ def gradient(f, *varargs, axis=None, edge_order=1): array([0. , 0.5, 1. ]) >>> np.heaviside(a, 1) array([0., 1., 1.]) + """ heaviside = DPNPBinaryFunc( @@ -2594,7 +2642,8 @@ def gradient(f, *varargs, axis=None, edge_order=1): Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Argument of the Bessel function, expected to have floating-point data type. + Argument of the Bessel function, 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. @@ -2620,6 +2669,7 @@ def gradient(f, *varargs, axis=None, edge_order=1): array(1.) >>> np.i0(np.array([0, 1, 2, 3])) array([1. , 1.26606588, 2.2795853 , 4.88079259]) + """ i0 = DPNPI0( @@ -2631,14 +2681,15 @@ def gradient(f, *varargs, axis=None, edge_order=1): _IMAG_DOCSTRING = """ -Computes imaginary part of each element `x_i` for input array `x`. +Returns the imaginary component of a complex number for each element :math:`x_i` +of the 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. + Input array, may have any data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -2680,6 +2731,7 @@ def gradient(f, *varargs, axis=None, edge_order=1): >>> np.imag(np.array(1 + 1j)) array(1.) + """ imag = DPNPImag( @@ -2690,8 +2742,8 @@ def gradient(f, *varargs, axis=None, edge_order=1): ) -_LCM_DOCSTRING = """ -Returns the lowest common multiple of ``|x1|`` and ``|x2|``. +_LCM_DOCSTRING = r""" +Returns the lowest common multiple of :math:`\abs{x1}` and :math:`\abs{x2}`. For full documentation refer to :obj:`numpy.lcm`. @@ -2699,12 +2751,8 @@ def gradient(f, *varargs, axis=None, edge_order=1): ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} First input array, expected to have an integer 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 an integer data type. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -2730,6 +2778,13 @@ def gradient(f, *varargs, axis=None, edge_order=1): -------- :obj:`dpnp.gcd` : The greatest common divisor. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -2737,6 +2792,7 @@ def gradient(f, *varargs, axis=None, edge_order=1): array(60) >>> np.lcm(np.arange(6), 20) array([ 0, 20, 20, 60, 20, 20]) + """ lcm = DPNPBinaryFunc( @@ -2749,23 +2805,20 @@ def gradient(f, *varargs, axis=None, edge_order=1): _LDEXP_DOCSTRING = """ -Returns x1 * 2**x2, element-wise. +Returns :math:`x1 * 2^{x2}`, element-wise. -The mantissas `x1` and exponents of two `x2` are used to construct floating point -numbers ``x1 * 2**x2``. +The mantissas `x1` and exponents of two `x2` are used to construct +floating-point numbers :math:`x1 * 2^{x2}`. For full documentation refer to :obj:`numpy.ldexp`. Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - Array of multipliers, expected to have floating-point data types. - Both inputs `x1` and `x2` can not be scalars at the same time. + Array of multipliers, expected to have a real-valued floating-point data + type. x2 : {dpnp.ndarray, usm_ndarray, scalar} Array of exponents of two, expected to have an integer data type. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -2779,7 +2832,7 @@ def gradient(f, *varargs, axis=None, edge_order=1): Returns ------- out : dpnp.ndarray - The result of ``x1 * 2**x2``. + The result of :math:`x1 * 2^{x2}`. Limitations ----------- @@ -2789,20 +2842,27 @@ def gradient(f, *varargs, axis=None, edge_order=1): See Also -------- -:obj:`dpnp.frexp` : Return (y1, y2) from ``x = y1 * 2**y2``, inverse to :obj:`dpnp.ldexp`. +:obj:`dpnp.frexp` : Return (y1, y2) from :math:`x = y1 * 2^{y2}`, + inverse to :obj:`dpnp.ldexp`. Notes ----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Complex dtypes are not supported, they will raise a ``TypeError``. :obj:`dpnp.ldexp` is useful as the inverse of :obj:`dpnp.frexp`, if used by -itself it is more clear to simply use the expression ``x1 * 2**x2``. +itself it is more clear to simply use the expression :math:`x1 * 2^{x2}`. Examples -------- >>> import dpnp as np >>> np.ldexp(5, np.arange(4)) array([ 5., 10., 20., 40.]) + """ ldexp = DPNPBinaryFunc( @@ -2815,26 +2875,23 @@ def gradient(f, *varargs, axis=None, edge_order=1): _MAXIMUM_DOCSTRING = """ -Compares two input arrays `x1` and `x2` and returns a new array containing the -element-wise maxima. +Computes the maximum value for each element :math:`x1_i` of the input array `x1` +relative to the respective element :math:`x2_i` of the input array `x2`. -If one of the elements being compared is a NaN, then that element is returned. -If both elements are NaNs then the first is returned. The latter distinction is -important for complex NaNs, which are defined as at least one of the real or -imaginary parts being a NaN. The net effect is that NaNs are propagated. +If one of the elements being compared is a ``NaN``, then that element is +returned. If both elements are NaNs then the first is returned. The latter +distinction is important for complex NaNs, which are defined as at least one of +the real or imaginary parts being a ``NaN``. The net effect is that NaNs are +propagated. For full documentation refer to :obj:`numpy.maximum`. Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, may have any data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also may have any data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -2867,6 +2924,13 @@ def gradient(f, *varargs, axis=None, edge_order=1): :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. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -2888,6 +2952,7 @@ def gradient(f, *varargs, axis=None, edge_order=1): >>> np.maximum(np.array(np.inf), 1) array(inf) + """ maximum = DPNPBinaryFunc( @@ -2899,26 +2964,23 @@ def gradient(f, *varargs, axis=None, edge_order=1): _MINIMUM_DOCSTRING = """ -Compares two input arrays `x1` and `x2` and returns a new array containing the -element-wise minima. +Computes the minimum value for each element :math:`x1_i` of the input array `x1` +relative to the respective element :math:`x2_i` of the input array `x2`. -If one of the elements being compared is a NaN, then that element is returned. -If both elements are NaNs then the first is returned. The latter distinction is -important for complex NaNs, which are defined as at least one of the real or -imaginary parts being a NaN. The net effect is that NaNs are propagated. +If one of the elements being compared is a ``NaN``, then that element is +returned. If both elements are NaNs then the first is returned. The latter +distinction is important for complex NaNs, which are defined as at least one of +the real or imaginary parts being a ``NaN``. The net effect is that NaNs are +propagated. For full documentation refer to :obj:`numpy.minimum`. Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, may have any data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output).s + Second input array, also may have any data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -2951,6 +3013,13 @@ def gradient(f, *varargs, axis=None, edge_order=1): :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. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -3021,21 +3090,17 @@ def modf(x1, **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`. +Calculates the product for each element :math:`x1_i` of the input array `x1` +with the respective element :math:`x2_i` of the input array `x2`. For full documentation refer to :obj:`numpy.multiply`. Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, may have any data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also may have any data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -3060,7 +3125,12 @@ def modf(x1, **kwargs): Notes ----- -Equivalent to `x1` * `x2` in terms of array broadcasting. +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + +Equivalent to :math:`x1 * x2` in terms of array broadcasting. Examples -------- @@ -3083,6 +3153,7 @@ def modf(x1, **kwargs): array([[ 0., 1., 4.], [ 0., 4., 10.], [ 0., 7., 16.]]) + """ multiply = DPNPBinaryFunc( @@ -3237,14 +3308,15 @@ def nan_to_num(x, copy=True, nan=0.0, posinf=None, neginf=None): _NEGATIVE_DOCSTRING = """ -Computes the numerical negative for each element `x_i` of input array `x`. +Computes the numerical negative of each element :math:`x_i` (i.e., +:math:`y_i = -x_i`) of the 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. + Input array, expected to have a 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. @@ -3283,6 +3355,7 @@ def nan_to_num(x, copy=True, nan=0.0, posinf=None, neginf=None): >>> x = np.array([1., -1.]) >>> -x array([-1., 1.]) + """ negative = DPNPUnaryFunc( @@ -3302,13 +3375,11 @@ def nan_to_num(x, copy=True, nan=0.0, posinf=None, neginf=None): Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - Values to find the next representable value of. - Both inputs `x1` and `x2` can not be scalars at the same time. + Values to find the next representable value of, expected to have a + real-valued floating-point data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - The direction where to look for the next representable value of `x1`. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + The direction where to look for the next representable value of `x1`, + also 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. @@ -3331,6 +3402,13 @@ def nan_to_num(x, copy=True, nan=0.0, posinf=None, neginf=None): Keyword argument `kwargs` is currently unsupported. Otherwise ``NotImplementedError`` exception will be raised. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as np @@ -3344,6 +3422,7 @@ def nan_to_num(x, copy=True, nan=0.0, posinf=None, neginf=None): >>> c = np.array([eps + 1, 2 - eps]) >>> np.nextafter(a, b) == c array([ True, True]) + """ nextafter = DPNPBinaryFunc( @@ -3357,14 +3436,15 @@ def nan_to_num(x, copy=True, nan=0.0, posinf=None, neginf=None): _POSITIVE_DOCSTRING = """ -Computes the numerical positive for each element `x_i` of input array `x`. +Computes the numerical positive of each element :math:`x_i` (i.e., +:math:`y_i = +x_i`) of the 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. + Input array, expected to have a 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. @@ -3407,6 +3487,7 @@ def nan_to_num(x, copy=True, nan=0.0, posinf=None, neginf=None): >>> x = np.array([1., -1.]) >>> +x array([ 1., -1.]) + """ positive = DPNPUnaryFunc( @@ -3419,8 +3500,9 @@ def nan_to_num(x, copy=True, nan=0.0, posinf=None, neginf=None): _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`. +Calculates :math:`x1_i` raised to :math:`x2_i` for each element :math:`x1_i` of +the input array `x1` with the respective element :math:`x2_i` of the input +array `x2`. Note that :obj:`dpnp.pow` is an alias of :obj:`dpnp.power`. @@ -3429,13 +3511,9 @@ def nan_to_num(x, copy=True, nan=0.0, posinf=None, neginf=None): Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, expected to have a numeric data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also expected to have a 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. @@ -3466,6 +3544,13 @@ def nan_to_num(x, copy=True, nan=0.0, posinf=None, neginf=None): :obj:`dpnp.fmod` : Calculate the element-wise remainder of division. :obj:`dpnp.float_power` : Power function that promotes integers to floats. +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Examples -------- >>> import dpnp as dp @@ -3494,11 +3579,12 @@ def nan_to_num(x, copy=True, nan=0.0, posinf=None, neginf=None): >>> a ** b array([ 0, 1, 8, 27, 16, 5]) -Negative values raised to a non-integral value will result in ``nan``. +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( @@ -3619,12 +3705,12 @@ def prod( _PROJ_DOCSTRING = """ -Computes projection of each element `x_i` for input array `x`. +Computes the complex projection of each element :math:`x_i` for input array `x`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + Input array, expected to have a complex 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. @@ -3659,6 +3745,7 @@ def prod( >>> 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]) + """ proj = DPNPUnaryFunc( @@ -3670,14 +3757,15 @@ def prod( _REAL_DOCSTRING = """ -Computes real part of each element `x_i` for input array `x`. +Returns the real component of a complex number for each element :math:`x_i` of +the input array `x`. For full documentation refer to :obj:`numpy.real`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + Input array, may have any data type. out : {None, dpnp.ndarray, usm_ndarray}, optional Output array to populate. Array must have the correct shape and the expected data type. @@ -3718,6 +3806,7 @@ def prod( array([9.+2.j, 8.+4.j, 7.+6.j]) >>> np.real(np.array(1 + 1j)) array(1.) + """ real = DPNPReal( @@ -3793,8 +3882,8 @@ def real_if_close(a, tol=100): _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`. +Calculates the remainder of division for each element :math:`x1_i` of the input +array `x1` with the respective element :math:`x2_i` of the input array `x2`. This function is equivalent to the Python modulus operator. @@ -3804,12 +3893,8 @@ def real_if_close(a, tol=100): ---------- 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. @@ -3824,7 +3909,7 @@ def real_if_close(a, tol=100): ------- out : dpnp.ndarray An array containing the element-wise remainders. Each remainder has the - same sign as respective element `x2_i`. The data type of the returned + same sign as respective element :math:`x2_i`. The data type of the returned array is determined by the Type Promotion Rules. Limitations @@ -3838,13 +3923,20 @@ def real_if_close(a, tol=100): :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.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. Notes ----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + Returns ``0`` when `x2` is ``0`` and both `x1` and `x2` are (arrays of) integers. + :obj:`dpnp.mod` is an alias of :obj:`dpnp.remainder`. Examples @@ -3862,6 +3954,7 @@ def real_if_close(a, tol=100): >>> x1 = np.arange(7) >>> x1 % 5 array([0, 1, 2, 3, 4, 0, 1]) + """ remainder = DPNPBinaryFunc( @@ -3876,18 +3969,18 @@ def real_if_close(a, tol=100): _RINT_DOCSTRING = """ -Rounds each element `x_i` of the input array `x` to -the nearest integer-valued number. +Rounds each element :math:`x_i` of the input array `x` to the nearest +integer-valued number. -When two integers are equally close to `x_i`, the result is the nearest even -integer to `x_i`. +When two integers are equally close to :math:`x_i`, the result is the nearest +even integer to :math:`x_i`. For full documentation refer to :obj:`numpy.rint`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + Input array, expected to have a 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. @@ -3923,6 +4016,7 @@ def real_if_close(a, tol=100): >>> 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.]) + """ @@ -3937,18 +4031,18 @@ def real_if_close(a, tol=100): _ROUND_DOCSTRING = """ -Rounds each element `x_i` of the input array `x` to -the nearest integer-valued number. +Rounds each element :math:`x_i` of the input array `x` to the nearest +integer-valued number. -When two integers are equally close to `x_i`, the result is the nearest even -integer to `x_i`. +When two integers are equally close to :math:`x_i`, the result is the nearest +even integer to :math:`x_i`. For full documentation refer to :obj:`numpy.round`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + Input array, expected to have a 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. @@ -3986,6 +4080,7 @@ def real_if_close(a, tol=100): array([ 1, 2, 3, 11]) >>> np.round(np.array([1, 2, 3, 11]), decimals=-1) array([ 0, 0, 0, 10]) + """ round = DPNPRound( @@ -3998,19 +4093,27 @@ def real_if_close(a, tol=100): ) -_SIGN_DOCSTRING = """ -Computes an indication of the sign of each element `x_i` of input array `x` -using the signum function. +_SIGN_DOCSTRING = r""" +Returns an indication of the sign of a number for each element :math:`x_i` of +the input array `x`. + +The sign function (also known as the **signum function**) of a number +:math:`x_i` is defined as + +.. math:: + \operatorname{sign}(x_i) = \begin{cases} + 0 & \textrm{if } x_i = 0 \\ + \frac{x_i}{|x_i|} & \textrm{otherwise} + \end{cases} -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`. +where :math:`|x_i|` is the absolute value of :math:`x_i`. For full documentation refer to :obj:`numpy.sign`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + Input array, expected to have a 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. @@ -4047,6 +4150,7 @@ def real_if_close(a, tol=100): array(0) >>> np.sign(np.array(5-2j)) array([1+0j]) + """ sign = DPNPUnaryFunc( @@ -4059,15 +4163,19 @@ def real_if_close(a, tol=100): _SIGNBIT_DOCSTRING = """ -Computes an indication of whether the sign bit of each element `x_i` of -input array `x` is set. +Determines whether the sign bit is set for each element :math:`x_i` of the +input array `x`. + +The sign bit of a real-valued floating-point number :math:`x_i` is set whenever +:math:`x_i` is either ``-0``, less than zero, or a signed ``NaN`` +(i.e., a ``NaN`` value whose sign bit is ``1``). For full documentation refer to :obj:`numpy.signbit`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + 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. @@ -4102,6 +4210,7 @@ def real_if_close(a, tol=100): >>> np.signbit(np.array([1, -2.3, 2.1])) array([False, True, False]) + """ signbit = DPNPUnaryFunc( @@ -4124,7 +4233,7 @@ def real_if_close(a, tol=100): Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have floating-point data type. + 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. @@ -4167,6 +4276,7 @@ def real_if_close(a, tol=100): 0. , 0.08504448, 0.12613779, 0.11643488, 0.06682066, 0. , -0.05846808, -0.08903844, -0.08409186, -0.04923628, 0. ]) + """ sinc = DPNPSinc( @@ -4186,7 +4296,7 @@ def real_if_close(a, tol=100): ---------- x : {dpnp.ndarray, usm_ndarray} The array of values to find the spacing of, expected to have a real-valued - data type. + 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. @@ -4225,6 +4335,7 @@ def real_if_close(a, tol=100): >>> b = np.spacing(a) >>> b == np.finfo(b.dtype).eps array(True) + """ spacing = DPNPUnaryFunc( @@ -4236,21 +4347,17 @@ def real_if_close(a, tol=100): _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`. +Calculates the difference for each element :math:`x1_i` of the input array `x1` +with the respective element :math:`x2_i` of the input array `x2`. For full documentation refer to :obj:`numpy.subtract`. Parameters ---------- x1 : {dpnp.ndarray, usm_ndarray, scalar} - First input array, expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. + First input array, expected to have a numeric data type. x2 : {dpnp.ndarray, usm_ndarray, scalar} - Second input array, also expected to have numeric data type. - Both inputs `x1` and `x2` can not be scalars at the same time. - If ``x1.shape != x2.shape``, they must be broadcastable to a common shape - (which becomes the shape of the output). + Second input array, also expected to have a 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. @@ -4275,7 +4382,12 @@ def real_if_close(a, tol=100): Notes ----- -Equivalent to `x1` - `x2` in terms of array broadcasting. +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + +Equivalent to :math:`x1 - x2` in terms of array broadcasting. Examples -------- @@ -4297,6 +4409,7 @@ def real_if_close(a, tol=100): array([[ 0., 0., 0.], [ 3., 3., 3.], [ 6., 6., 6.]]) + """ subtract = DPNPBinaryFunc( @@ -4543,7 +4656,7 @@ def trapezoid(y, x=None, dx=1.0, axis=-1): _TRUNC_DOCSTRING = """ -Returns the truncated value for each element `x_i` for input array `x`. +Returns the truncated value for each element :math:`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 @@ -4588,6 +4701,7 @@ def trapezoid(y, x=None, dx=1.0, axis=-1): >>> 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 = DPNPUnaryFunc( diff --git a/dpnp/dpnp_iface_trigonometric.py b/dpnp/dpnp_iface_trigonometric.py index 6a4e2398f3f9..fff45f92f96b 100644 --- a/dpnp/dpnp_iface_trigonometric.py +++ b/dpnp/dpnp_iface_trigonometric.py @@ -109,31 +109,34 @@ def _get_accumulation_res_dt(a, dtype): _ACOS_DOCSTRING = r""" -Computes inverse cosine for each element `x_i` for input array `x`. +Computes inverse cosine for each element :math:`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`. +The inverse of :obj:`dpnp.cos` so that, if :math:`y = cos(x)`, then +:math:`x = acos(y)`. Note that :obj:`dpnp.arccos` is an alias of +:obj:`dpnp.acos`. -For full documentation refer to :obj:`numpy.arccos`. +For full documentation refer to :obj:`numpy.acos`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + 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 : {None, "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. + An array containing the element-wise inverse cosine, in radians and in the + closed interval :math:`[0, \pi]`. The data type of the returned array is + determined by the Type Promotion Rules. Limitations ----------- @@ -144,36 +147,38 @@ def _get_accumulation_res_dt(a, dtype): 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. +:obj:`dpnp.atan` : Trigonometric inverse tangent, element-wise. +:obj:`dpnp.asin` : Trigonometric inverse sine, element-wise. +:obj:`dpnp.acosh` : 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]`. +:obj:`dpnp.acos` is a multivalued function: for each `x` there are infinitely +many numbers `z` such that :math:`cos(z) = x`. The convention is to return the +angle `z` whose the real part lies in the interval :math:`[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 real-valued floating-point input data types, :obj:`dpnp.acos` 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. +For complex floating-point input data types, :obj:`dpnp.acos` is a complex +analytic function that has, by convention, the branch cuts +:math:`(-\infty, -1)` and :math:`(1, \infty)` 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}`. +The inverse cosine is also known as :math:`cos^{-1}`. Examples -------- >>> import dpnp as np >>> x = np.array([1, -1]) ->>> np.arccos(x) +>>> np.acos(x) array([0.0, 3.14159265]) + """ -arccos = DPNPUnaryFunc( - "arccos", +acos = DPNPUnaryFunc( + "acos", ti._acos_result_type, ti._acos, _ACOS_DOCSTRING, @@ -181,35 +186,39 @@ def _get_accumulation_res_dt(a, dtype): mkl_impl_fn="_acos", ) -acos = arccos # acos is an alias for arccos +arccos = acos # arccos is an alias for acos _ACOSH_DOCSTRING = r""" -Computes inverse hyperbolic cosine for each element `x_i` for input array `x`. +Computes inverse hyperbolic cosine for each element :math:`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`. +The inverse of :obj:`dpnp.cosh` so that, if :math:`y = cosh(x)`, then +:math:`x = acosh(y)`. Note that :obj:`dpnp.arccosh` is an alias of +:obj:`dpnp.acosh`. -For full documentation refer to :obj:`numpy.arccosh`. +For full documentation refer to :obj:`numpy.acosh`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + 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 : {None, "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. + An array containing the element-wise inverse hyperbolic cosine, in radians + and in the half-closed interval :math:`[0, \infty)`. The data type of the + returned array is determined by the Type Promotion Rules. Limitations ----------- @@ -220,37 +229,40 @@ def _get_accumulation_res_dt(a, dtype): See Also -------- :obj:`dpnp.cosh` : Hyperbolic cosine, element-wise. -:obj:`dpnp.arcsinh` : Hyperbolic inverse sine, element-wise. +:obj:`dpnp.asinh` : Hyperbolic inverse sine, element-wise. :obj:`dpnp.sinh` : Hyperbolic sine, element-wise. -:obj:`dpnp.arctanh` : Hyperbolic inverse tangent, element-wise. +:obj:`dpnp.atanh` : Hyperbolic inverse tangent, element-wise. :obj:`dpnp.tanh` : Hyperbolic tangent, element-wise. -:obj:`dpnp.arccos` : Trigonometric inverse cosine, element-wise. +:obj:`dpnp.acos` : 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]`. +:obj:`dpnp.acosh` is a multivalued function: for each `x` there are infinitely +many numbers `z` such that :math:`cosh(z) = x`. The convention is to return the +angle `z` whose the real part lies in the interval :math:`[0, \infty)` and the +imaginary part in the interval :math:`[-\pi, \pi]`. -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 real-valued floating-point input data types, :obj:`dpnp.acosh` 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. +For complex floating-point input data types, :obj:`dpnp.acosh` is a complex +analytic function that has, by convention, the branch cuts :math:`(-\infty, 1)` +and is continuous from above on it. -The inverse hyperbolic cos is also known as :math:`acosh` or :math:`cosh^{-1}`. +The inverse hyperbolic cosine is also known as :math:`cosh^{-1}`. Examples -------- >>> import dpnp as np >>> x = np.array([1.0, np.e, 10.0]) ->>> np.arccosh(x) +>>> np.acosh(x) array([0.0, 1.65745445, 2.99322285]) + """ -arccosh = DPNPUnaryFunc( - "arccosh", +acosh = DPNPUnaryFunc( + "acosh", ti._acosh_result_type, ti._acosh, _ACOSH_DOCSTRING, @@ -258,35 +270,37 @@ def _get_accumulation_res_dt(a, dtype): mkl_impl_fn="_acosh", ) -acosh = arccosh # acosh is an alias for arccosh +arccosh = acosh # arccosh is an alias for acosh _ASIN_DOCSTRING = r""" -Computes inverse sine for each element `x_i` for input array `x`. +Computes inverse sine for each element :math:`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`. +The inverse of :obj:`dpnp.sin`, so that if :math:`y = sin(x)` then +:math:`x = asin(y)`. Note that :obj:`dpnp.arcsin` is an alias of :obj:`dpnp.asin`. -For full documentation refer to :obj:`numpy.arcsin`. +For full documentation refer to :obj:`numpy.asin`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + 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 : {None, "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. + An array containing the element-wise inverse sine, in radians and in the + closed interval :math:`[-\pi/2, \pi/2]`. The data type of the returned + array is determined by the Type Promotion Rules. Limitations ----------- @@ -298,38 +312,41 @@ def _get_accumulation_res_dt(a, dtype): -------- :obj:`dpnp.sin` : Trigonometric sine, element-wise. :obj:`dpnp.cos` : Trigonometric cosine, element-wise. -:obj:`dpnp.arccos` : Trigonometric inverse cosine, element-wise. +:obj:`dpnp.acos` : 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. +:obj:`dpnp.atan` : Trigonometric inverse tangent, element-wise. +:obj:`dpnp.atan2` : Element-wise arc tangent of :math:`\frac{x1}{x2}` + choosing the quadrant correctly. +:obj:`dpnp.asinh` : 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]`. +:obj:`dpnp.asin` is a multivalued function: for each `x` there are infinitely +many numbers `z` such that :math:`sin(z) = x`. The convention is to return the +angle `z` whose the real part lies in the interval :math:`[-\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 real-valued floating-point input data types, :obj:`dpnp.asin` 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. +For complex floating-point input data types, :obj:`dpnp.asin` is a complex +analytic function that has, by convention, the branch cuts +:math:`(-\infty, -1)` and :math:`(1, \infty)` 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}`. +The inverse sine is also known as :math:`sin^{-1}`. Examples -------- >>> import dpnp as np >>> x = np.array([0, 1, -1]) ->>> np.arcsin(x) +>>> np.asin(x) array([0.0, 1.5707963267948966, -1.5707963267948966]) + """ -arcsin = DPNPUnaryFunc( - "arcsin", +asin = DPNPUnaryFunc( + "asin", ti._asin_result_type, ti._asin, _ASIN_DOCSTRING, @@ -337,35 +354,39 @@ def _get_accumulation_res_dt(a, dtype): mkl_impl_fn="_asin", ) -asin = arcsin # asin is an alias for arcsin +arcsin = asin # arcsin is an alias for asin _ASINH_DOCSTRING = r""" -Computes inverse hyperbolic sine for each element `x_i` for input array `x`. +Computes inverse hyperbolic sine for each element :math:`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`. +The inverse of :obj:`dpnp.sinh`, so that if :math:`y = sinh(x)` then +:math:`x = asinh(y)`. Note that :obj:`dpnp.arcsinh` is an alias of +:obj:`dpnp.asinh`. -For full documentation refer to :obj:`numpy.arcsinh`. +For full documentation refer to :obj:`numpy.asinh`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + 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 : {None, "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. + An array containing the element-wise inverse hyperbolic sine, in radians. + The data type of the returned array is determined by the Type Promotion + Rules. Limitations ----------- @@ -376,37 +397,38 @@ def _get_accumulation_res_dt(a, dtype): 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. +:obj:`dpnp.atanh` : Hyperbolic inverse tangent, element-wise. +:obj:`dpnp.acosh` : Hyperbolic inverse cosine, element-wise. +:obj:`dpnp.asin` : 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``. +:obj:`dpnp.asinh` is a multivalued function: for each `x` there are infinitely +many numbers `z` such that :math:`sin(z) = x`. The convention is to return the +angle `z` whose the imaginary part lies in the interval :math:`[-\pi/2, \pi/2]`. -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. +For real-valued floating-point input data types, :obj:`dpnp.asinh` always +returns real output. For each value that cannot be expressed as a real number +or infinity, it yields ``NaN``. -The inverse hyperbolic sine is also known as :math:`asinh` or :math:`sinh^{-1}`. +For complex floating-point input data types, :obj:`dpnp.asinh` is a complex +analytic function that has, by convention, the branch cuts +:math:`(-\infty j, -j)` and :math:`(j, \infty j)` and is continuous from the left +on the former and from the right on the latter. +The inverse hyperbolic sine is also known as :math:`sinh^{-1}`. Examples -------- >>> import dpnp as np >>> x = np.array([np.e, 10.0]) ->>> np.arcsinh(x) +>>> np.asinh(x) array([1.72538256, 2.99822295]) + """ -arcsinh = DPNPUnaryFunc( - "arcsinh", +asinh = DPNPUnaryFunc( + "asinh", ti._asinh_result_type, ti._asinh, _ASINH_DOCSTRING, @@ -414,35 +436,38 @@ def _get_accumulation_res_dt(a, dtype): mkl_impl_fn="_asinh", ) -asinh = arcsinh # asinh is an alias for arcsinh +arcsinh = asinh # arcsinh is an alias for asinh _ATAN_DOCSTRING = r""" -Computes inverse tangent for each element `x_i` for input array `x`. +Computes inverse tangent for each element :math:`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`. +The inverse of :obj:`dpnp.tan`, so that if :math:`y = tan(x)` then +:math:`x = atan(y)`. Note that :obj:`dpnp.arctan` is an alias of +:obj:`dpnp.atan`. -For full documentation refer to :obj:`numpy.arctan`. +For full documentation refer to :obj:`numpy.atan`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + 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 : {None, "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. + An array containing the element-wise inverse tangent, in radians and in the + closed interval :math:`[-\pi/2, \pi/2]`. The data type of the returned + array is determined by the Type Promotion Rules. Limitations ----------- @@ -452,39 +477,42 @@ def _get_accumulation_res_dt(a, dtype): See Also -------- -:obj:`dpnp.arctan2` : Element-wise arc tangent of `x1/x2` choosing the quadrant correctly. +:obj:`dpnp.atan2` : Element-wise arc tangent of :math:`\frac{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. +:obj:`dpnp.asin` : Trigonometric inverse sine, element-wise. +:obj:`dpnp.acos` : Trigonometric inverse cosine, element-wise. +:obj:`dpnp.atanh` : 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]`. +:obj:`dpnp.atan` is a multivalued function: for each `x` there are infinitely +many numbers `z` such that :math:`tan(z) = x`. The convention is to return the +angle `z` whose the real part lies in the interval :math:`[-\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 real-valued floating-point input data types, :obj:`dpnp.atan` 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. +For complex floating-point input data types, :obj:`dpnp.atan` is a complex +analytic function that has, by convention, the branch cuts +:math:`(-\infty j, -j)` and :math:`(j, \infty j)` and is continuous from the right +on the former and from the left on the latter. -The inverse tan is also known as :math:`atan` or :math:`tan^{-1}`. +The inverse tangent is also known as :math:`tan^{-1}`. Examples -------- >>> import dpnp as np >>> x = np.array([0, 1]) ->>> np.arctan(x) +>>> np.atan(x) array([0.0, 0.78539816]) + """ -arctan = DPNPUnaryFunc( - "arctan", +atan = DPNPUnaryFunc( + "atan", ti._atan_result_type, ti._atan, _ATAN_DOCSTRING, @@ -492,83 +520,88 @@ def _get_accumulation_res_dt(a, dtype): mkl_impl_fn="_atan", ) -atan = arctan # atan is an alias for arctan +arctan = atan # arctan is an alias for atan -_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. +_ATAN2_DOCSTRING = r""" +Calculates the inverse tangent of the quotient :math:`\frac{x1_i}{x2_i}` for +each element :math:`x1_i` of the input array `x1` with the respective element +:math:`x2_i` of the input array `x2`. -Note that :obj:`dpnp.atan2` is an alias of :obj:`dpnp.arctan2`. +Note that :obj:`dpnp.arctan2` is an alias of :obj:`dpnp.atan2`. 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`. +For full documentation refer to :obj:`numpy.atan2`. 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. + First input array, expected to have a real-valued floating-point data type. 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). + Second input array, also 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 : {None, "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. + An array containing the inverse tangent of the quotient + :math:`\frac{x1}{x2}`, in radians. 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. +Keyword argument `kwargs` is currently unsupported. Otherwise ``NotImplementedError`` exception will be raised. See Also -------- -:obj:`dpnp.arctan` : Trigonometric inverse tangent, element-wise. +:obj:`dpnp.atan` : 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. +:obj:`dpnp.asin` : Trigonometric inverse sine, element-wise. +:obj:`dpnp.acos` : Trigonometric inverse cosine, element-wise. +:obj:`dpnp.atanh` : Inverse hyperbolic tangent, element-wise. + +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). Examples -------- >>> import dpnp as np >>> x1 = np.array([1., -1.]) >>> x2 = np.array([0., 0.]) ->>> np.arctan2(x1, x2) +>>> np.atan2(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) +>>> np.atan2(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 +>>> np.atan2(x1, x2) * 180 / np.pi array([-135., -45., 45., 135.]) + """ -arctan2 = DPNPBinaryFunc( - "arctan2", +atan2 = DPNPBinaryFunc( + "atan2", ti._atan2_result_type, ti._atan2, _ATAN2_DOCSTRING, @@ -576,35 +609,39 @@ def _get_accumulation_res_dt(a, dtype): mkl_impl_fn="_atan2", ) -atan2 = arctan2 # atan2 is an alias for arctan2 +arctan2 = atan2 # arctan2 is an alias for atan2 _ATANH_DOCSTRING = r""" -Computes hyperbolic inverse tangent for each element `x_i` for input array `x`. +Computes hyperbolic inverse tangent for each element :math:`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`. +The inverse of :obj:`dpnp.tanh`, so that if :math:`y = tanh(x)` then +:math:`x = atanh(y)`. Note that :obj:`dpnp.arctanh` is an alias of +:obj:`dpnp.atanh`. -For full documentation refer to :obj:`numpy.arctanh`. +For full documentation refer to :obj:`numpy.atanh`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + 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 : {None, "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. + An array containing the element-wise inverse hyperbolic tangent, in + radians. The data type of the returned array is determined by the Type + Promotion Rules. Limitations ----------- @@ -615,36 +652,38 @@ def _get_accumulation_res_dt(a, dtype): 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. +:obj:`dpnp.asinh` : Hyperbolic inverse sine, element-wise. +:obj:`dpnp.acosh` : Hyperbolic inverse cosine, element-wise. +:obj:`dpnp.atan` : 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]`. +:obj:`dpnp.atanh` is a multivalued function: for each `x` there are infinitely +many numbers `z` such that :math:`tanh(z) = x`. The convention is to return the +angle `z` whose the imaginary part lies in the interval :math:`[-\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 real-valued floating-point input data types, :obj:`dpnp.atanh` 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. +For complex floating-point input data types, :obj:`dpnp.atanh` is a complex +analytic function that has, by convention, the branch cuts +:math:`(-\infty, -1]` and :math:`[1, \infty)` and 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}`. +The inverse hyperbolic tangent is also known as :math:`tanh^{-1}`. Examples -------- >>> import dpnp as np >>> x = np.array([0, -0.5]) ->>> np.arctanh(x) +>>> np.atanh(x) array([0.0, -0.54930614]) + """ -arctanh = DPNPUnaryFunc( - "arctanh", +atanh = DPNPUnaryFunc( + "atanh", ti._atanh_result_type, ti._atanh, _ATANH_DOCSTRING, @@ -652,32 +691,33 @@ def _get_accumulation_res_dt(a, dtype): mkl_impl_fn="_atanh", ) -atanh = arctanh # atanh is an alias for arctanh +arctanh = atanh # arctanh is an alias for atanh -_CBRT_DOCSTRING = """ -Computes positive cube-root for each element `x_i` for input array `x`. +_CBRT_DOCSTRING = r""" +Computes the cube-root for each element :math:`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. + 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 : {None, "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. + An array containing the element-wise cube-root. The data type of the + returned array is determined by the Type Promotion Rules. Limitations ----------- @@ -687,7 +727,11 @@ def _get_accumulation_res_dt(a, dtype): See Also -------- -:obj:`dpnp.sqrt` : Return the positive square-root of an array, element-wise. +:obj:`dpnp.sqrt` : Calculate :math:`\sqrt{x}`, element-wise. + +Notes +----- +This function is equivalent to :math:`\sqrt[3]{x}`, element-wise. Examples -------- @@ -695,6 +739,7 @@ def _get_accumulation_res_dt(a, dtype): >>> x = np.array([1, 8, 27]) >>> np.cbrt(x) array([1., 2., 3.]) + """ cbrt = DPNPUnaryFunc( @@ -708,27 +753,29 @@ def _get_accumulation_res_dt(a, dtype): _COS_DOCSTRING = """ -Computes cosine for each element `x_i` for input array `x`. +Computes the cosine for each element :math:`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. + 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 : {None, "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. + An array containing the element-wise cosine, in radians. The data type of + the returned array is determined by the Type Promotion Rules. Limitations ----------- @@ -738,7 +785,7 @@ def _get_accumulation_res_dt(a, dtype): See Also -------- -:obj:`dpnp.arccos` : Trigonometric inverse cosine, element-wise. +:obj:`dpnp.acos` : 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. @@ -749,6 +796,7 @@ def _get_accumulation_res_dt(a, dtype): >>> x = np.array([0, np.pi/2, np.pi]) >>> np.cos(x) array([ 1.000000e+00, -4.371139e-08, -1.000000e+00]) + """ cos = DPNPUnaryFunc( @@ -761,28 +809,34 @@ def _get_accumulation_res_dt(a, dtype): ) -_COSH_DOCSTRING = """ -Computes hyperbolic cosine for each element `x_i` for input array `x`. +_COSH_DOCSTRING = r""" +Computes the hyperbolic cosine for each element :math:`x_i` for input array `x`. + +The mathematical definition of the hyperbolic cosine is + +.. math:: \operatorname{cosh}(x) = \frac{e^x + e^{-x}}{2} For full documentation refer to :obj:`numpy.cosh`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + 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 : {None, "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. + An array containing the element-wise hyperbolic cosine. The data type of + the returned array is determined by the Type Promotion Rules. Limitations ----------- @@ -792,7 +846,7 @@ def _get_accumulation_res_dt(a, dtype): See Also -------- -:obj:`dpnp.arccosh` : Hyperbolic inverse cosine, element-wise. +:obj:`dpnp.acosh` : 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. @@ -804,6 +858,7 @@ def _get_accumulation_res_dt(a, dtype): >>> x = np.array([0, np.pi/2, np.pi]) >>> np.cosh(x) array([1.0, 2.5091786, 11.591953]) + """ cosh = DPNPUnaryFunc( @@ -826,11 +881,13 @@ def cumlogsumexp( Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have a real-valued data type. + Input array, expected to have a boolean or real-valued floating-point + 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, str, dtype object}, optional Data type of the returned array. If ``None``, the default data type is @@ -847,16 +904,20 @@ def cumlogsumexp( 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. + A boolean indicating whether to include the initial value (negative + infinity) as the first value along the provided axis in the output. + With ``include_initial=True`` the shape of the output is different than + the shape of the input. + 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 @@ -867,15 +928,15 @@ def cumlogsumexp( 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. + Note + ---- + This function is equivalent of `numpy.logaddexp.accumulate`. + Examples -------- >>> import dpnp as np @@ -903,28 +964,32 @@ def cumlogsumexp( ) -_DEG2RAD_DOCSTRING = """ -Convert angles from degrees to radians. +_DEG2RAD_DOCSTRING = r""" +Convert angles from degrees to radians for each element :math:`x_i` for input +array `x`. For full documentation refer to :obj:`numpy.deg2rad`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Angles in degrees. + 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 : {None, "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. + An array containing the element-wise angle in radians. + The data type of the returned array is determined by the Type Promotion + Rules. Limitations ----------- @@ -940,7 +1005,9 @@ def cumlogsumexp( Notes ----- -dpnp.deg2rad(x) is ``x * pi / 180``. +The mathematical definition is + +.. math:: \operatorname{deg2rad}(x) = \frac{x * \pi}{180} Examples -------- @@ -948,6 +1015,7 @@ def cumlogsumexp( >>> x = np.array(180) >>> np.deg2rad(x) array(3.14159265) + """ deg2rad = DPNPUnaryFunc( @@ -958,28 +1026,32 @@ def cumlogsumexp( ) -_DEGREES_DOCSTRING = """ -Convert angles from radians to degrees. +_DEGREES_DOCSTRING = r""" +Convert angles from radian to degrees for each element :math:`x_i` for input +array `x`. For full documentation refer to :obj:`numpy.degrees`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array in radians. + 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 : {None, "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. + An array containing the element-wise angle in degrees. + The data type of the returned array is determined by the Type Promotion + Rules. Limitations ----------- @@ -991,6 +1063,12 @@ def cumlogsumexp( -------- :obj:`dpnp.rad2deg` : Equivalent function. +Notes +----- +The mathematical definition is + +.. math:: \operatorname{degrees}(x) = \frac{180 * x}{\pi} + Examples -------- >>> import dpnp as np @@ -1006,6 +1084,7 @@ def cumlogsumexp( >>> r = np.degrees(rad, out) >>> np.all(r == out) array(True) + """ degrees = DPNPUnaryFunc( @@ -1017,28 +1096,30 @@ def cumlogsumexp( _EXP_DOCSTRING = """ -Computes the exponent for each element `x_i` of input array `x`. +Computes the exponential for each element :math:`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. + 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 : {None, "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. + An array containing the element-wise exponential of `x`. + The data type of the returned array is determined by the Type Promotion + Rules. Limitations ----------- @@ -1048,8 +1129,8 @@ def cumlogsumexp( 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. +:obj:`dpnp.expm1` : Calculate :math:`e^x - 1`, element-wise. +:obj:`dpnp.exp2` : Calculate :math:`2^x`, element-wise. Examples -------- @@ -1057,6 +1138,7 @@ def cumlogsumexp( >>> x = np.arange(3.) >>> np.exp(x) array([1.0, 2.718281828, 7.389056099]) + """ exp = DPNPUnaryFunc( @@ -1070,7 +1152,8 @@ def cumlogsumexp( _EXP2_DOCSTRING = """ -Computes the base-2 exponent for each element `x_i` for input array `x`. +Computes the base-2 exponential for each element :math:`x_i` for input array +`x`. For full documentation refer to :obj:`numpy.exp2`. @@ -1081,17 +1164,19 @@ def cumlogsumexp( 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 : {None, "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. + An array containing the element-wise base-2 exponentials. + The data type of the returned array is determined by the Type Promotion + Rules. Limitations ----------- @@ -1101,9 +1186,9 @@ def cumlogsumexp( 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. +:obj:`dpnp.exp` : Calculate :math:`e^x`, element-wise. +:obj:`dpnp.expm1` : Calculate :math:`e^x - 1`, element-wise. +:obj:`dpnp.power` : Calculate :math:`{x1}^{x2}`, element-wise. Examples -------- @@ -1111,6 +1196,7 @@ def cumlogsumexp( >>> x = np.arange(3.) >>> np.exp2(x) array([1., 2., 4.]) + """ exp2 = DPNPUnaryFunc( @@ -1123,31 +1209,32 @@ def cumlogsumexp( ) -_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`. +_EXPM1_DOCSTRING = r""" +Computes the exponential minus ``1`` for each element :math:`x_i` of input +array `x`. For full documentation refer to :obj:`numpy.expm1`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + 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 : {None, "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. + An array containing containing the evaluated result for each element in `x`. + The data type of the returned array is determined by the Type Promotion + Rules. Limitations ----------- @@ -1157,9 +1244,15 @@ def cumlogsumexp( 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`. +:obj:`dpnp.exp` : Calculate :math:`e^x`, element-wise. +:obj:`dpnp.exp2` : Calculate :math:`2^x`, element-wise. +:obj:`dpnp.log1p` : Calculate :math:`\log(1 + x)`, element-wise, + the inverse of :obj:`dpnp.expm1`. + +Notes +----- +This function provides greater precision than :math:`e^x - 1` for small values +of `x`. Examples -------- @@ -1173,6 +1266,7 @@ def cumlogsumexp( >>> np.exp(np.array(1e-10)) - 1 array(1.000000082740371e-10) + """ expm1 = DPNPUnaryFunc( @@ -1185,35 +1279,35 @@ def cumlogsumexp( ) -_HYPOT_DOCSTRING = """ -Calculates the hypotenuse for a right triangle with "legs" `x1_i` and `x2_i` of -input arrays `x1` and `x2`. +_HYPOT_DOCSTRING = r""" +Computes the square root of the sum of squares for each element :math:`x1_i` of +the input array `x1` with the respective element :math:`x2_i` of the input +array `x2`. For full documentation refer to :obj:`numpy.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. + First input array, expected to have a real-valued floating-point data type. 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). + Second input array, also 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 : {None, "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. + An array containing the element-wise hypotenuse. The data type of the + returned array is determined by the Type Promotion Rules. Limitations ----------- @@ -1223,7 +1317,17 @@ def cumlogsumexp( See Also -------- -:obj:`dpnp.reduce_hypot` : The square root of the sum of squares of elements in the input array. +:obj:`dpnp.reduce_hypot` : The square root of the sum of squares of elements + in the input array. + +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + +This function is equivalent to :math:`\sqrt{x1^2 + x2^2}`, element-wise. Examples -------- @@ -1241,6 +1345,7 @@ def cumlogsumexp( array([[ 5., 5., 5.], [ 5., 5., 5.], [ 5., 5., 5.]]) + """ hypot = DPNPBinaryFunc( @@ -1253,42 +1358,60 @@ def cumlogsumexp( ) -_LOG_DOCSTRING = """ -Computes the natural logarithm for each element `x_i` of input array `x`. +_LOG_DOCSTRING = r""" +Computes the natural logarithm for each element :math:`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. + 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 : {None, "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. + 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. +Keyword argument `kwargs` is currently unsupported. 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. +:obj:`dpnp.log10` : Calculate :math:`\log_{10}(x)`, element-wise. +:obj:`dpnp.log2` : Calculate :math:`\log_2(x)`, element-wise. +:obj:`dpnp.log1p` : Calculate :math:`\log(1 + x)`, element-wise. + +Notes +----- +:obj:`dpnp.log` is a multivalued function: for each `x` there are infinitely +many numbers `z` such that :math:`e^z = x`. The convention is to return the `z` +whose the imaginary part lies in the interval :math:`[-\pi, \pi]`. + +For real-valued floating-point input data types, :obj:`dpnp.log` always returns +real output. For each value that cannot be expressed as a real number or +nfinity, it yields ``NaN``. + +For complex floating-point input data types, :obj:`dpnp.log` is a complex +analytic function that has, by convention, the branch cuts +:math:`(-\infty, 0)` and is continuous from above on it. + +In the cases where the input has a negative real part and a very small negative +complex part (approaching 0), the result is so close to :math:`-\pi` that it +evaluates to exactly :math:`-\pi`. Examples -------- @@ -1296,6 +1419,7 @@ def cumlogsumexp( >>> x = np.array([1, np.e, np.e**2, 0]) >>> np.log(x) array([ 0., 1., 2., -inf]) + """ log = DPNPUnaryFunc( @@ -1308,29 +1432,30 @@ def cumlogsumexp( ) -_LOG10_DOCSTRING = """ -Computes the base-10 logarithm for each element `x_i` of input array `x`. +_LOG10_DOCSTRING = r""" +Computes the base-10 logarithm for each element :math:`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. + 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 : {None, "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. + 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 ----------- @@ -1340,9 +1465,27 @@ def cumlogsumexp( 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. +:obj:`dpnp.log` : Calculate :math:`\log(x)`, element-wise. +:obj:`dpnp.log2` : Calculate :math:`\log_2(x)`, element-wise. +:obj:`dpnp.log1p` : Calculate :math:`\log(1 + x)`, element-wise. + +Notes +----- +:obj:`dpnp.log10` is a multivalued function: for each `x` there are infinitely +many numbers `z` such that :math:`10^z = x`. The convention is to return the `z` +whose the imaginary part lies in the interval :math:`[-\pi, \pi]`. + +For real-valued floating-point input data types, :obj:`dpnp.log10` always +returns real output. For each value that cannot be expressed as a real number +or nfinity, it yields ``NaN``. + +For complex floating-point input data types, :obj:`dpnp.log10` is a complex +analytic function that has, by convention, the branch cuts +:math:`(-\infty, 0)` and is continuous from above on it. + +In the cases where the input has a negative real part and a very small negative +complex part (approaching 0), the result is so close to :math:`-\pi` that it +evaluates to exactly :math:`-\pi`. Examples -------- @@ -1353,6 +1496,7 @@ def cumlogsumexp( >>> np.log10(np.array([1e-15, -3.])) array([-15., nan]) + """ log10 = DPNPUnaryFunc( @@ -1365,31 +1509,31 @@ def cumlogsumexp( ) -_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`. +_LOG1P_DOCSTRING = r""" +Computes the natural logarithm of (1 + `x`) for each element :math:`x_i` of +input array `x`. For full documentation refer to :obj:`numpy.log1p`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + 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 : {None, "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. + An array containing the element-wise :math:`\log(1 + x)` results. The data + type of the returned array is determined by the Type Promotion Rules. Limitations ----------- @@ -1399,10 +1543,29 @@ def cumlogsumexp( 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. +:obj:`dpnp.expm1` : Calculate :math:`e^x - 1`, element-wise, + the inverse of :obj:`dpnp.log1p`. +:obj:`dpnp.log` : Calculate :math:`\log(x)`, element-wise. +:obj:`dpnp.log10` : Calculate :math:`\log_{10}(x)`, element-wise. +:obj:`dpnp.log2` : Calculate :math:`\log_2(x)`, element-wise. + +Notes +----- +For real-valued floating-point input data types, :obj:`dpnp.log1p` provides +greater precision than :math:`\log(1 + x)` for `x` so small that +:math:`1 + x == 1`. + +:obj:`dpnp.log1p` is a multivalued function: for each `x` there are infinitely +many numbers `z` such that :math:`e^z = 1 + x`. The convention is to return the +`z` whose the imaginary part lies in the interval :math:`[-\pi, \pi]`. + +For real-valued floating-point input data types, :obj:`dpnp.log1p` always +returns real output. For each value that cannot be expressed as a real number +or nfinity, it yields ``NaN``. + +For complex floating-point input data types, :obj:`dpnp.log1p` is a complex +analytic function that has, by convention, the branch cuts +:math:`(-\infty, 0)` and is continuous from above on it. Examples -------- @@ -1416,6 +1579,7 @@ def cumlogsumexp( >>> np.log(array(1 + 1e-99)) array(0.0) + """ log1p = DPNPUnaryFunc( @@ -1428,29 +1592,30 @@ def cumlogsumexp( ) -_LOG2_DOCSTRING = """ -Computes the base-2 logarithm for each element `x_i` of input array `x`. +_LOG2_DOCSTRING = r""" +Computes the base-2 logarithm for each element :math:`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. + 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 : {None, "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. + 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 ----------- @@ -1460,9 +1625,27 @@ def cumlogsumexp( 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. +:obj:`dpnp.log` : Calculate :math:`\log(x)`, element-wise. +:obj:`dpnp.log10` : Calculate :math:`\log_{10}(x)`, element-wise. +:obj:`dpnp.log1p` : Calculate :math:`\log(1 + x)`, element-wise. + +Notes +----- +:obj:`dpnp.log2` is a multivalued function: for each `x` there are infinitely +many numbers `z` such that :math:`2^z = x`. The convention is to return the `z` +whose the imaginary part lies in the interval :math:`[-\pi, \pi]`. + +For real-valued floating-point input data types, :obj:`dpnp.log2` always +returns real output. For each value that cannot be expressed as a real number +or nfinity, it yields ``NaN``. + +For complex floating-point input data types, :obj:`dpnp.log2` is a complex +analytic function that has, by convention, the branch cuts +:math:`(-\infty, 0)` and is continuous from above on it. + +In the cases where the input has a negative real part and a very small negative +complex part (approaching 0), the result is so close to :math:`-\pi` that it +evaluates to exactly :math:`-\pi`. Examples -------- @@ -1474,6 +1657,7 @@ def cumlogsumexp( >>> 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( @@ -1486,13 +1670,10 @@ def cumlogsumexp( ) -_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`. +_LOGADDEXP_DOCSTRING = r""" +Calculates the natural logarithm of the sum of exponentiations +:math:`\log(e^{x1} + e^{x2})` for each element :math:`x1_i` of the input array +`x1` with the respective element :math:`x2_i` of the input array `x2`. For full documentation refer to :obj:`numpy.logaddexp`. @@ -1501,41 +1682,50 @@ def cumlogsumexp( 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). + Second input array, also 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 : {None, "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. + 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. +Keyword argument `kwargs` is 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. +:obj:`dpnp.log` : Calculate :math:`\log(x)`, element-wise. +:obj:`dpnp.exp` : Calculate :math:`e^x`, element-wise. +:obj:`dpnp.logaddexp2`: Calculate :math:`\log_2(2^{x1} + 2^{x2})`, element-wise. +:obj:`dpnp.logsumexp` : Logarithm of the sum of exponentials of elements in the + input array. + +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + +This function is useful in statistics where the calculated probabilities of +events may be so small as to exceed the range of normal floating-point numbers. +In such cases the natural logarithm of the calculated probability is stored. +This function allows adding probabilities stored in such a fashion. Examples -------- @@ -1547,6 +1737,7 @@ def cumlogsumexp( array(-113.87649168) >>> np.exp(prob12) array(3.5e-50) + """ logaddexp = DPNPBinaryFunc( @@ -1557,16 +1748,10 @@ def cumlogsumexp( ) -_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. +_LOGADDEXP2_DOCSTRING = r""" +Calculates the base-2 logarithm of the sum of exponentiations +:math:`\log_2(2^{x1} + 2^{x2})` for each element :math:`x1_i` of the input +array `x1` with the respective element :math:`x2_i` of the input array `x2`. For full documentation refer to :obj:`numpy.logaddexp2`. @@ -1575,19 +1760,17 @@ def cumlogsumexp( 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). + Second input array, also 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 : {None, "C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is ``None``. + Default: ``"K"``. Returns @@ -1599,14 +1782,27 @@ def cumlogsumexp( Limitations ----------- Parameters `where` and `subok` are supported with their default values. -Keyword arguments `kwargs` are currently unsupported. +Keyword argument `kwargs` is 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. +:obj:`dpnp.logaddexp`: Calculate :math:`\log(e^{x1} + e^{x2})`, element-wise. +:obj:`dpnp.logsumexp` : Logarithm of the sum of exponentials of elements in the + input array. + +Notes +----- +At least one of `x1` or `x2` must be an array. + +If ``x1.shape != x2.shape``, they must be broadcastable to a common shape +(which becomes the shape of the output). + +This function 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. Examples -------- @@ -1618,6 +1814,7 @@ def cumlogsumexp( (array(-166.09640474), array(-164.77447665), array(-164.28904982)) >>> 2**prob12 array(3.5e-50) + """ logaddexp2 = DPNPBinaryFunc( @@ -1629,18 +1826,20 @@ def cumlogsumexp( def logsumexp(x, /, *, axis=None, dtype=None, keepdims=False, out=None): - """ - Calculates the logarithm of the sum of exponents of elements in + r""" + Calculates the natural logarithm of the sum of exponentials of elements in the input array. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have a real-valued data type. + Input array, expected to have a boolean or real-valued floating-point + 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, str, dtype object}, optional Data type of the returned array. If ``None``, the default data type is @@ -1657,6 +1856,7 @@ def logsumexp(x, /, *, axis=None, dtype=None, keepdims=False, out=None): 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 @@ -1668,6 +1868,7 @@ def logsumexp(x, /, *, axis=None, dtype=None, keepdims=False, out=None): 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 @@ -1678,19 +1879,21 @@ def logsumexp(x, /, *, axis=None, dtype=None, keepdims=False, out=None): has the data type as described in the `dtype` parameter description above. + See Also + -------- + :obj:`dpnp.log` : Calculate :math:`\log(x)`, element-wise. + :obj:`dpnp.exp` : Calculate :math:`e^x`, element-wise. + :obj:`dpnp.logaddexp`: Calculate :math:`\log(e^{x1} + e^{x2})`, + element-wise. + :obj:`dpnp.logaddexp2`: Calculate :math:`\log_2(2^{x1} + 2^{x2})`, + element-wise. + :obj:`dpnp.cumlogsumexp` : Cumulative the natural logarithm of the sum of + elements in the input array. + 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 @@ -1714,28 +1917,32 @@ def logsumexp(x, /, *, axis=None, dtype=None, keepdims=False, out=None): ) -_RAD2DEG_DOCSTRING = """ -Convert angles from radians to degrees. +_RAD2DEG_DOCSTRING = r""" +Convert angles from radians to degrees for each element :math:`x_i` for input +array `x`. For full documentation refer to :obj:`numpy.rad2deg`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Angle in radians. + 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 : {None, "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. + An array containing the element-wise angle in degrees. + The data type of the returned array is determined by the Type Promotion + Rules. Limitations ----------- @@ -1751,7 +1958,9 @@ def logsumexp(x, /, *, axis=None, dtype=None, keepdims=False, out=None): Notes ----- -dpnp.rad2deg(x) is ``180 * x / pi``. +The mathematical definition is + +.. math:: \operatorname{rad2deg}(x) = \frac{180 * x}{\pi} Examples -------- @@ -1759,6 +1968,7 @@ def logsumexp(x, /, *, axis=None, dtype=None, keepdims=False, out=None): >>> x = np.array(np.pi / 2) >>> np.rad2deg(x) array(90.) + """ rad2deg = DPNPUnaryFunc( @@ -1769,28 +1979,32 @@ def logsumexp(x, /, *, axis=None, dtype=None, keepdims=False, out=None): ) -_RADIANS_DOCSTRING = """ -Convert angles from degrees to radians. +_RADIANS_DOCSTRING = r""" +Convert angles from degrees to radians for each element :math:`x_i` for input +array `x`. For full documentation refer to :obj:`numpy.radians`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array in degrees. + 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 : {None, "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. + An array containing the element-wise angle in radians. + The data type of the returned array is determined by the Type Promotion + Rules. Limitations ----------- @@ -1802,6 +2016,12 @@ def logsumexp(x, /, *, axis=None, dtype=None, keepdims=False, out=None): -------- :obj:`dpnp.deg2rad` : Equivalent function. +Notes +----- +The mathematical definition is + +.. math:: \operatorname{radians}(x) = \frac{x * \pi}{180} + Examples -------- >>> import dpnp as np @@ -1818,6 +2038,7 @@ def logsumexp(x, /, *, axis=None, dtype=None, keepdims=False, out=None): >>> ret = np.radians(deg, out) >>> ret is out True + """ radians = DPNPUnaryFunc( @@ -1828,29 +2049,30 @@ def logsumexp(x, /, *, axis=None, dtype=None, keepdims=False, out=None): ) -_RECIPROCAL_DOCSTRING = """ -Computes the reciprocal square-root for each element `x_i` for input array `x`. +_RECIPROCAL_DOCSTRING = r""" +Computes the reciprocal for each element :math:`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. + 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 : {None, "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. + An array containing the element-wise reciprocals. The returned array has + a floating-point data type determined by the Type Promotion Rules. Limitations ----------- @@ -1860,7 +2082,11 @@ def logsumexp(x, /, *, axis=None, dtype=None, keepdims=False, out=None): See Also -------- -:obj:`dpnp.rsqrt` : Return the reciprocal square-root of an array, element-wise. +:obj:`dpnp.rsqrt` : Calculate :math:`\frac{1}{\sqrt{x}}`, element-wise. + +Notes +----- +This function is equivalent to :math:`\frac{1}{x}`, element-wise. Examples -------- @@ -1868,6 +2094,7 @@ def logsumexp(x, /, *, axis=None, dtype=None, keepdims=False, out=None): >>> x = np.array([1, 2., 3.33]) >>> np.reciprocal(x) array([1.0, 0.5, 0.3003003]) + """ reciprocal = DPNPUnaryFunc( @@ -1879,18 +2106,20 @@ def logsumexp(x, /, *, axis=None, dtype=None, keepdims=False, out=None): def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): - """ + r""" 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. + Input array, expected to have a boolean or real-valued floating-point + 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, str, dtype object}, optional Data type of the returned array. If ``None``, the default data type is @@ -1907,6 +2136,7 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): 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 @@ -1918,6 +2148,7 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): 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 @@ -1928,15 +2159,14 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): has the data type as described in the `dtype` parameter description above. + See Also + -------- + :obj:`dpnp.hypot` : Calculates :math:`\sqrt{x1^2 + x2^2}`, element-wise. + 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 @@ -1960,16 +2190,18 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): ) -_RSQRT_DOCSTRING = """ -Computes the reciprocal square-root for each element `x_i` for input array `x`. +_RSQRT_DOCSTRING = r""" +Computes the reciprocal square-root for each element :math:`x_i` for input +array `x`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have a real floating-point data type. + 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 : {None, "C", "F", "A", "K"}, optional Memory layout of the newly output array, if parameter `out` is `None`. @@ -1978,7 +2210,7 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): Returns ------- out : dpnp.ndarray - An array containing the element-wise reciprocal square-root. + An array containing the element-wise reciprocal square-roots. The returned array has a floating-point data type determined by the Type Promotion Rules. @@ -1990,8 +2222,12 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): 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. +:obj:`dpnp.sqrt` : Calculate :math:`\sqrt{x}`, element-wise. +:obj:`dpnp.reciprocal` : Calculate :math:`\frac{1}{x}`, element-wise. + +Notes +----- +This function is equivalent to :math:`\frac{1}{\sqrt{x}}`, element-wise. Examples -------- @@ -1999,6 +2235,7 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): >>> x = np.array([1, 8, 27]) >>> np.rsqrt(x) array([1. , 0.35355338, 0.19245009]) + """ rsqrt = DPNPUnaryFunc( @@ -2010,26 +2247,28 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): _SIN_DOCSTRING = """ -Computes sine for each element `x_i` of input array `x`. +Computes the sine for each element :math:`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. + 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 : {None, "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 + An array containing the element-wise sine, in radians. The data type of the returned array is determined by the Type Promotion Rules. Limitations @@ -2040,7 +2279,7 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): See Also -------- -:obj:`dpnp.arcsin` : Trigonometric inverse sine, element-wise. +:obj:`dpnp.asin` : 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. @@ -2051,6 +2290,7 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): >>> x = np.array([0, np.pi/2, np.pi]) >>> np.sin(x) array([ 0.000000e+00, 1.000000e+00, -8.742278e-08]) + """ sin = DPNPUnaryFunc( @@ -2063,37 +2303,44 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): ) -_SINH_DOCSTRING = """ -Computes hyperbolic sine for each element `x_i` for input array `x`. +_SINH_DOCSTRING = r""" +Computes the hyperbolic sine for each element :math:`x_i` for input array `x`. + +The mathematical definition of the hyperbolic sine is + +.. math:: \operatorname{sinh}(x) = \frac{e^x - e^{-x}}{2} For full documentation refer to :obj:`numpy.sinh`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + 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 : {None, "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. + An array containing the element-wise 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.arcsinh` : Hyperbolic inverse sine, element-wise. +:obj:`dpnp.asinh` : 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. @@ -2104,6 +2351,7 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): >>> x = np.array([0, np.pi/2, np.pi]) >>> np.sinh(x) array([0.0, 2.3012989, 11.548739]) + """ sinh = DPNPUnaryFunc( @@ -2116,39 +2364,57 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): ) -_SQRT_DOCSTRING = """ -Computes the positive square-root for each element `x_i` of input array `x`. +_SQRT_DOCSTRING = r""" +Computes the principal square-root for each element :math:`x_i` of input array +`x`. For full documentation refer to :obj:`numpy.sqrt`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array. + 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 : {None, "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. + An array containing the element-wise principal 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. +Keyword argument `kwargs` is currently unsupported. 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. +:obj:`dpnp.cbrt` : Calculate :math:`\sqrt[3]{x}`, element-wise. +:obj:`dpnp.rsqrt` : Calculate :math:`\frac{1}{\sqrt{x}}`, element-wise. + +Notes +----- +This function is equivalent to :math:`\sqrt{x}`, element-wise. + +By convention, the branch cut of the square root is the negative real axis +:math:`(-\infty, 0)`. + +The square root is a continuous function from above the branch cut, taking into +account the sign of the imaginary component. + +Accordingly, for complex arguments, the function returns the square root in the +range of the right half-plane, including the imaginary axis (i.e., the plane +defined by :math:`[0, +\infty)` along the real axis and +:math:`(-\infty, +\infty)` along the imaginary axis). Examples -------- @@ -2160,6 +2426,7 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): >>> x2 = np.array([4, -1, np.inf]) >>> np.sqrt(x2) array([ 2., nan, inf]) + """ sqrt = DPNPUnaryFunc( @@ -2172,42 +2439,43 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): ) -_SQUARE_DOCSTRING = """ -Squares each element `x_i` of input array `x`. +_SQUARE_DOCSTRING = r""" +Squares each element :math:`x_i` of input array `x`. For full documentation refer to :obj:`numpy.square`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array. + Input array, may have any 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 : {None, "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. + 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. +Keyword argument `kwargs` is currently unsupported. 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. +:obj:`dpnp.linalg.matrix_power` : Raise a square matrix to the (integer) + power `n`. +:obj:`dpnp.sqrt` : Calculate :math:`\sqrt{x}`, element-wise. +:obj:`dpnp.power` : Calculate :math:`{x1}^{x2}`, element-wise. Examples -------- @@ -2215,6 +2483,7 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): >>> x = np.array([-1j, 1]) >>> np.square(x) array([-1.+0.j, 1.+0.j]) + """ square = DPNPUnaryFunc( @@ -2228,27 +2497,29 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): _TAN_DOCSTRING = """ -Computes tangent for each element `x_i` for input array `x`. +Computes the tangent for each element :math:`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. + 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 : {None, "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. + An array containing the element-wise tangent, in radians. The data type of + the returned array is determined by the Type Promotion Rules. Limitations ----------- @@ -2258,7 +2529,7 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): See Also -------- -:obj:`dpnp.arctan` : Trigonometric inverse tangent, element-wise. +:obj:`dpnp.atan` : 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. @@ -2269,6 +2540,7 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): >>> 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( @@ -2281,28 +2553,36 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): ) -_TANH_DOCSTRING = """ -Computes hyperbolic tangent for each element `x_i` for input array `x`. +_TANH_DOCSTRING = r""" +Computes the hyperbolic tangent for each element :math:`x_i` for input array +`x`. + +The mathematical definition of the hyperbolic tangent is + +.. math:: + \operatorname{tanh}(x) = \frac{\operatorname{sinh}(x)}{\operatorname{cosh}(x)} For full documentation refer to :obj:`numpy.tanh`. Parameters ---------- x : {dpnp.ndarray, usm_ndarray} - Input array, expected to have numeric data type. + 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 : {None, "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. + An array containing the element-wise hyperbolic tangent. The data type of + the returned array is determined by the Type Promotion Rules. Limitations ----------- @@ -2312,7 +2592,7 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): See Also -------- -:obj:`dpnp.arctanh` : Hyperbolic inverse tangent, element-wise. +:obj:`dpnp.atanh` : 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. @@ -2323,6 +2603,7 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False, out=None): >>> 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( @@ -2340,8 +2621,9 @@ def unwrap(p, discont=None, axis=-1, *, period=2 * dpnp.pi): 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. + difference from their predecessor of more than + :math:`\max(discont, \frac{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 @@ -2356,15 +2638,19 @@ def unwrap(p, discont=None, axis=-1, *, period=2 * dpnp.pi): 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``. + alias for :math:`\frac{period}{2}`. Values below + :math:`\frac{period}{2}` are treated as if they were + :math:`\frac{period}{2}`. To have an effect different from the default, + `discont` should be larger than :math:`\frac{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 @@ -2379,9 +2665,9 @@ def unwrap(p, discont=None, axis=-1, *, period=2 * dpnp.pi): 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. + If the discontinuity in `p` is smaller than :math:`\frac{period}{2}`, but + larger than `discont`, no unwrapping is done because taking the complement + would only make the discontinuity larger. Examples --------