:mod:`heat.array_api._elementwise_functions`
============================================
.. py:module:: heat.array_api._elementwise_functions


Module Contents
---------------


.. function:: abs(x: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

   Calculates the absolute value for each element ``x_i`` of the input array ``x``
   (i.e., the element-wise result has the same magnitude as the respective
   element in ``x`` but has positive sign).

   :param x: Input array. Must have a numeric data type.
   :type x: Array


.. function:: acos(x: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

   Calculates an approximation of the principal value of the inverse cosine,
   having domain ``[-1, +1]`` and codomain ``[+0, +π]``, for each element ``x_i``
   of the input array ``x``. Each element-wise result is expressed in radians.

   :param x: Input array. Must have a floating-point data type.
   :type x: Array


.. function:: acosh(x: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

   Calculates an approximation to the inverse hyperbolic cosine, having domain
   ``[+1, +infinity]`` and codomain ``[+0, +infinity]``, for each element ``x_i``
   of the input array ``x``.

   :param x: Input array whose elements each represent the area of a hyperbolic sector.
             Must have a floating-point data type.
   :type x: Array


.. function:: add(x1: heat.array_api._array_object.Array, x2: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

   Calculates the sum for each element ``x1_i`` of the input array ``x1`` with
   the respective element ``x2_i`` of the input array ``x2``.

   :param x1: First input array. Must have a numeric data type.
   :type x1: Array
   :param x2: Second input array. Must be compatible with ``x1`` and have a numeric
              data type.
   :type x2: Array


.. function:: asin(x: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

   Calculates an approximation of the principal value of the inverse sine, having
   domain ``[-1, +1]`` and codomain ``[-π/2, +π/2]`` for each element ``x_i`` of
   the input array ``x``. Each element-wise result is expressed in radians.

   :param x: Input array. Must have a floating-point data type.
   :type x: Array


.. function:: asinh(x: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

   Calculates an approximation to the inverse hyperbolic sine, having domain
   ``[-infinity, +infinity]`` and codomain ``[-infinity, +infinity]``, for each
   element ``x_i`` in the input array ``x``.

   :param x: Input array whose elements each represent the area of a hyperbolic sector.
             Must have a floating-point data type.
   :type x: Array


.. function:: atan(x: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

   Calculates an implementation-dependent approximation of the principal value of
   the inverse tangent, having domain ``[-infinity, +infinity]`` and codomain
   ``[-π/2, +π/2]``, for each element ``x_i`` of the input array ``x``.
   Each element-wise result is expressed in radians.

   :param x: Input array. Must have a floating-point data type.
   :type x: Array


.. function:: atan2(x1: heat.array_api._array_object.Array, x2: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

   Calculates an approximation of the inverse tangent of the quotient ``x1/x2``,
   having domain ``[-infinity, +infinity] x [-infinity, +infinity]`` (where the
   ``x`` notation denotes the set of ordered pairs of elements ``(x1_i, x2_i)``)
   and codomain ``[-π, +π]``, for each pair of elements ``(x1_i, x2_i)`` of the
   input arrays ``x1`` and ``x2``, respectively. Each element-wise result is
   expressed in radians.

   The mathematical signs of ``x1_i`` and ``x2_i`` determine the quadrant of each
   element-wise result. The quadrant (i.e., branch) is chosen such that each
   element-wise result is the signed angle in radians between the ray ending at the
   origin and passing through the point ``(1,0)`` and the ray ending at the origin
   and passing through the point ``(x2_i, x1_i)``.

   :param x1: Input array corresponding to the y-coordinates. Must have a floating-point
              data type.
   :type x1: Array
   :param x2: Input array corresponding to the x-coordinates. Must be compatible with ``x1``
              and have a floating-point data type.
   :type x2: Array


.. function:: atanh(x: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

   Calculates an approximation to the inverse hyperbolic tangent, having domain
   ``[-1, +1]`` and codomain ``[-infinity, +infinity]``, for each element ``x_i``
   of the input array ``x``.

   :param x: Input array whose elements each represent the area of a hyperbolic sector.
             Must have a floating-point data type.
   :type x: Array


.. function:: bitwise_and(x1: heat.array_api._array_object.Array, x2: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

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

   :param x1: First input array. Must have an integer or boolean data type.
   :type x1: Array
   :param x2: Second input array. Must be compatible with ``x1`` and have an integer
              or boolean data type.
   :type x2: Array


.. function:: bitwise_left_shift(x1: heat.array_api._array_object.Array, x2: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

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

   :param x1: First input array. Must have an integer data type.
   :type x1: Array
   :param x2: Second input array. Must be compatible with ``x1`` and have an integer
              data type. Each element must be greater than or equal to ``0``.
   :type x2: Array


.. function:: bitwise_invert(x: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

   Inverts (flips) each bit for each element ``x_i`` of the input array ``x``.

   :param x: Input array. Must have an integer or boolean data type.
   :type x: Array


.. function:: bitwise_or(x1: heat.array_api._array_object.Array, x2: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

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

   :param x1: First input array. Must have an integer or boolean data type.
   :type x1: Array
   :param x2: Second input array. Must be compatible with ``x1`` and have an integer
              or boolean data type.
   :type x2: Array


.. function:: bitwise_right_shift(x1: heat.array_api._array_object.Array, x2: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

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

   :param x1: First input array. Must have an integer data type.
   :type x1: Array
   :param x2: Second input array. Must be compatible with ``x1`` and have an integer
              data type. Each element must be greater than or equal to ``0``.
   :type x2: Array


.. function:: bitwise_xor(x1: heat.array_api._array_object.Array, x2: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

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

   :param x1: First input array. Must have an integer or boolean data type.
   :type x1: Array
   :param x2: Second input array. Must be compatible with ``x1`` and have an integer
              or boolean data type.
   :type x2: Array


.. function:: ceil(x: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

   Rounds each element ``x_i`` of the input array ``x`` to the smallest (i.e., closest
   to ``-infinity``) integer-valued number that is not less than ``x_i``.

   :param x: Input array. Must have a numeric data type.
   :type x: Array


.. function:: cos(x: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

   Calculates an approximation to the cosine, having domain ``(-infinity, +infinity)``
   and codomain ``[-1, +1]``, for each element ``x_i`` of the input array ``x``.
   Each element ``x_i`` is assumed to be expressed in radians.

   :param x: Input array whose elements are each expressed in radians. Must have a
             floating-point data type.
   :type x: Array


.. function:: cosh(x: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

   Calculates an approximation to the hyperbolic cosine, having domain
   ``[-infinity, +infinity]`` and codomain ``[-infinity, +infinity]``, for each
   element ``x_i`` in the input array ``x``.

   :param x: Input array whose elements each represent a hyperbolic angle. Must have
             a floating-point data type.
   :type x: Array


.. function:: divide(x1: heat.array_api._array_object.Array, x2: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

   Calculates the division for each element ``x1_i`` of the input array ``x1``
   with the respective element ``x2_i`` of the input array ``x2``.

   :param x1: Dividend input array. Must have a numeric data type.
   :type x1: Array
   :param x2: Divisor input array. Must be compatible with ``x1`` and have a numeric
              data type.
   :type x2: Array


.. function:: equal(x1: heat.array_api._array_object.Array, x2: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

   Computes the truth value of ``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``.

   :param x1: First input array.
   :type x1: Array
   :param x2: Second input array. Must be compatible with ``x1``.
   :type x2: Array


.. function:: exp(x: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

   Calculates an approximation to the exponential function, having domain
   ``[-infinity, +infinity]`` and codomain ``[+0, +infinity]``, for each element
   ``x_i`` of the input array ``x`` (``e`` raised to the power of ``x_i``, where
   ``e`` is the base of the natural logarithm).

   :param x: Input array. Must have a floating-point data type.
   :type x: Array


.. function:: expm1(x: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

   Calculates an approximation to ``exp(x)-1``, having domain
   ``[-infinity, +infinity]`` and codomain ``[-1, +infinity]``, for each element
   ``x_i`` of the input array ``x``.

   :param x: Input array. Must have a floating-point data type.
   :type x: Array


.. function:: floor(x: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

   Rounds each element ``x_i`` of the input array ``x`` to the greatest
   (i.e., closest to ``+infinity``) integer-valued number that is not greater
   than ``x_i``.

   :param x: Input array. Must have a numeric data type.
   :type x: Array


.. function:: floor_divide(x1: heat.array_api._array_object.Array, x2: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

   Rounds the result of dividing each element ``x1_i`` of the input array ``x1``
   by the respective element ``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.

   :param x1: First input array. Must have a numeric data type.
   :type x1: Array
   :param x2: Second input array. Must be compatible with ``x1`` and have a numeric
              data type.
   :type x2: Array


.. function:: greater(x1: heat.array_api._array_object.Array, x2: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

   Computes the truth value of ``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``.

   :param x1: First input array. Must have a numeric data type.
   :type x1: Array
   :param x2: Second input array. Must be compatible with ``x1`` and have a numeric
              data type.
   :type x2: Array


.. function:: greater_equal(x1: heat.array_api._array_object.Array, x2: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

   Computes the truth value of ``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``.

   :param x1: First input array. Must have a numeric data type.
   :type x1: Array
   :param x2: Second input array. Must be compatible with ``x1`` and have a numeric
              data type.
   :type x2: Array


.. function:: isfinite(x: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

   Tests each element ``x_i`` of the input array ``x`` to determine if finite
   (i.e., not ``NaN`` and not equal to positive or negative infinity).

   :param x: Input array. Must have a numeric data type.
   :type x: Array


.. function:: isinf(x: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

   Tests each element ``x_i`` of the input array ``x`` to determine if equal
   to positive or negative infinity.

   :param x: Input array. Must have a numeric data type.
   :type x: Array


.. function:: isnan(x: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

   Tests each element ``x_i`` of the input array ``x`` to determine whether
   the element is ``NaN``.

   :param x: Input array. Must have a numeric data type.
   :type x: Array


.. function:: less(x1: heat.array_api._array_object.Array, x2: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

   Computes the truth value of ``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``.

   :param x1: First input array. Must have a numeric data type.
   :type x1: Array
   :param x2: Second input array. Must be compatible with ``x1`` and have a numeric
              data type.
   :type x2: Array


.. function:: less_equal(x1: heat.array_api._array_object.Array, x2: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

   Computes the truth value of ``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``.

   :param x1: First input array. Must have a numeric data type.
   :type x1: Array
   :param x2: Second input array. Must be compatible with ``x1`` and have a numeric
              data type.
   :type x2: Array


.. function:: log(x: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

   Calculates an  approximation to the natural (base ``e``) logarithm, having domain
   ``[0, +infinity]`` and codomain ``[-infinity, +infinity]``, for each element
   ``x_i`` of the input array ``x``.

   :param x: Input array. Must have a floating-point data type.
   :type x: Array


.. function:: log1p(x: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

   Calculates an approximation to ``log(1+x)``, where ``log`` refers to the natural
   (base ``e``) logarithm, having domain ``[-1, +infinity]`` and codomain
   ``[-infinity, +infinity]``, for each element ``x_i`` of the input array ``x``.

   :param x: Input array. Must have a floating-point data type.
   :type x: Array


.. function:: log2(x: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

   Calculates an approximation to the base ``2`` logarithm, having domain
   ``[0, +infinity]`` and codomain ``[-infinity, +infinity]``, for each element
   ``x_i`` of the input array ``x``.

   :param x: Input array. Must have a floating-point data type.
   :type x: Array


.. function:: log10(x: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

   Calculates an approximation to the base ``10`` logarithm, having domain
   ``[0, +infinity]`` and codomain ``[-infinity, +infinity]``, for each element
   ``x_i`` of the input array ``x``.

   :param x: Input array. Must have a floating-point data type.
   :type x: Array


.. function:: logaddexp(x1: heat.array_api._array_object.Array, x2: heat.array_api._array_object.Array) -> heat.array_api._array_object.Array

   Calculates the logarithm of the sum of exponentiations ``log(exp(x1) + exp(x2))``
   for each element ``x1_i`` of the input array ``x1`` with the respective element
   ``x2_i`` of the input array ``x2``.

   :param x1: First input array. Must have a floating-point data type.
   :type x1: Array
   :param x2: Second input array. Must be compatible with ``x1`` and have a floating-point
              data type.
   :type x2: Array


.. function:: logical_and(x1: heat.array_api._array_object.Array, x2: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

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

   :param x1: First input array. Must have a boolean data type.
   :type x1: Array
   :param x2: Second input array. Must be compatible with ``x1`` and have a boolean
              data type.
   :type x2: Array


.. function:: logical_not(x: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

   Computes the logical NOT for each element ``x_i`` of the input array ``x``.

   :param x: Input array. Must have a boolean data type.
   :type x: Array


.. function:: logical_or(x1: heat.array_api._array_object.Array, x2: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

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

   :param x1: First input array. Must have a boolean data type.
   :type x1: Array
   :param x2: Second input array. Must be compatible with ``x1`` and have a boolean
              data type.
   :type x2: Array


.. function:: logical_xor(x1: heat.array_api._array_object.Array, x2: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

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

   :param x1: First input array. Must have a boolean data type.
   :type x1: Array
   :param x2: Second input array. Must be compatible with ``x1`` and have a boolean
              data type.
   :type x2: Array


.. function:: multiply(x1: heat.array_api._array_object.Array, x2: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

   Calculates the product for each element ``x1_i`` of the input array ``x1``
   with the respective element ``x2_i`` of the input array ``x2``.

   :param x1: First input array. Must have a numeric data type.
   :type x1: Array
   :param x2: Second input array. Must be compatible with ``x1`` and have a numeric
              data type.
   :type x2: Array


.. function:: negative(x: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

   Computes the numerical negative of each element ``x_i``
   (i.e., ``y_i = -x_i``) of the input array ``x``.

   :param x: Input array. Must have a numeric data type.
   :type x: Array


.. function:: not_equal(x1: heat.array_api._array_object.Array, x2: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

   Computes the truth value of ``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``.

   :param x1: First input array.
   :type x1: Array
   :param x2: Second input array. Must be compatible with ``x1``.
   :type x2: Array


.. function:: positive(x: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

   Computes the numerical positive of each element ``x_i``
   (i.e., ``y_i = +x_i``) of the input array ``x``.

   :param x: Input array. Must have a numeric data type.
   :type x: Array


.. function:: pow(x1: heat.array_api._array_object.Array, x2: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

   Calculates an approximation of exponentiation by raising each element
   ``x1_i`` (the base) of the input array ``x1`` to the power of
   ``x2_i`` (the exponent), where ``x2_i`` is the corresponding element of
   the input array ``x2``.

   :param x1: First input array whose elements correspond to the exponentiation base.
              Must have a numeric data type.
   :type x1: Array
   :param x2: Second input array whose elements correspond to the exponentiation exponent.
              Must be compatible with ``x1`` and have a numeric
              data type.
   :type x2: Array


.. function:: remainder(x1: heat.array_api._array_object.Array, x2: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

   Returns the remainder of division for each element ``x1_i`` of the input
   array ``x1`` and the respective element ``x2_i`` of the input array ``x2``.

   :param x1: Dividend input array. Must have a numeric data type.
   :type x1: Array
   :param x2: Divisor input array. Must be compatible with ``x1`` and have a numeric
              data type.
   :type x2: Array


.. function:: round(x: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

   Rounds each element ``x_i`` of the input array ``x`` to the nearest
   integer-valued number.

   :param x: Input array. Must have a numeric data type.
   :type x: Array


.. function:: sign(x: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

   Returns an indication of the sign of a number for each element ``x_i`` of
   the input array ``x``.

   :param x: Input array. Must have a numeric data type.
   :type x: Array


.. function:: sin(x: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

   Calculates an approximation to the sine, having domain ``(-infinity, +infinity)``
   and codomain ``[-1, +1]``, for each element ``x_i`` of the input array ``x``.
   Each element ``x_i`` is assumed to be expressed in radians.

   :param x: Input array whose elements are each expressed in radians. Must have a
             floating-point data type.
   :type x: Array


.. function:: sinh(x: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

   Calculates an approximation to the hyperbolic sine, having domain
   ``[-infinity, +infinity]`` and codomain ``[-infinity, +infinity]``, for
   each element ``x_i`` of the input array ``x``.

   :param x: Input array whose elements each represent a hyperbolic angle. Must have
             a floating-point data type.
   :type x: Array


.. function:: square(x: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

   Squares ``(x_i * x_i)`` each element ``x_i`` of the input array ``x``.

   :param x: Input array. Must have a numeric data type.
   :type x: Array


.. function:: sqrt(x: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

   Calculates the square root, having domain ``[0, +infinity]`` and codomain
   ``[0, +infinity]``, for each element ``x_i`` of the input array ``x``.

   :param x: Input array. Must have a floating-point data type.
   :type x: Array


.. function:: subtract(x1: heat.array_api._array_object.Array, x2: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

   Calculates the difference for each element ``x1_i`` of the input array
   ``x1`` with the respective element ``x2_i`` of the input array ``x2``.

   :param x1: First input array. Must have a numeric data type.
   :type x1: Array
   :param x2: Second input array. Must be compatible with ``x1`` and have a numeric
              data type.
   :type x2: Array


.. function:: tan(x: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

   Calculates an approximation to the tangent, having domain ``(-infinity, +infinity)``
   and codomain ``(-infinity, +infinity)``, for each element ``x_i`` of the
   input array ``x``. Each element ``x_i`` is assumed to be expressed in radians.

   :param x: Input array whose elements are each expressed in radians. Must have a
             floating-point data type.
   :type x: Array


.. function:: tanh(x: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

   Calculates an approximation to the hyperbolic tangent, having domain
   ``[-infinity, +infinity]`` and codomain ``[-1, +1]``, for each element ``x_i``
   of the input array ``x``.

   :param x: Input array whose elements each represent a hyperbolic angle. Must have
             a floating-point data type.
   :type x: Array


.. function:: trunc(x: heat.array_api._array_object.Array, /) -> heat.array_api._array_object.Array

   Rounds each element ``x_i`` of the input array ``x`` to the integer-valued
   number that is closest to but no greater than ``x_i``.

   :param x: Input array. Must have a numeric data type.
   :type x: Array