Function pow

imperative/python/megengine/functional/elemwise.py:418–483

r"""Element-wise power. Calculates an implementation-dependent approximation of exponentiation by raising each element :math:`x_i` (the base) of the input tensor :math:`x` to the power of :math:`y_i` (the exponent), where :math:`y_i` is the corresponding element of the input tenso

(x: Tensor, y: Tensor)

def pow(x: Tensor, y: Tensor) -> Tensor:
    r"""Element-wise power.
    
    Calculates an implementation-dependent approximation of exponentiation by 
    raising each element :math:`x_i` (the base) of the input tensor :math:`x` to 
    the power of :math:`y_i` (the exponent), where :math:`y_i` is the corresponding element of the input tensor :math:`y`.

    Args:
        x: first input tensor whose elements correspond to the exponentiation base. Should have a numeric data type.
        y: second input tensor whose elements correspond to the exponentiation exponent.
            Must be compatible with `x` (see :ref:`broadcasting-rule` ). Should have a numeric data type.

    Returns:
        A tensor containing the element-wise results.
        The returned tensor must have a data type determined by :ref:`dtype-promotion`.

    .. note::

       The unary ``**`` operator can be used as a shorthand for ``pow`` on tensors.

    .. admonition:: Special cases

       For floating-point operands,

       * If :math:`x_i` is not equal to ``1`` and :math:`y_i` is ``NaN``, the result is ``NaN``.
       * If :math:`y_i` is ``+0``, the result is ``1``, even if :math:`x_i` is ``NaN``.
       * If :math:`y_i` is ``-0``, the result is ``1``, even if :math:`x_i` is ``NaN``.
       * If :math:`x_i` is ``NaN`` and :math:`y_i` is not equal to ``0``, the result is ``NaN``.
       * If :math:`\abs{x_i}` is greater than ``1`` and :math:`y_i` is ``+infinity``, the result is ``+infinity``.
       * If :math:`\abs{x_i}` is greater than ``1`` and :math:`y_i` is ``-infinity``, the result is ``+0``.
       * If :math:`\abs{x_i}` is ``1`` and :math:`y_i` is ``+infinity``, the result is ``1``.
       * If :math:`\abs{x_i}` is ``1`` and :math:`y_i` is ``-infinity``, the result is ``1``.
       * If :math:`x_i` is ``1`` and :math:`y_i` is not ``NaN``, the result is ``1``.
       * If :math:`\abs{x_i}` is less than ``1`` and :math:`y_i` is ``+infinity``, the result is ``+0``.
       * If :math:`\abs{x_i}` is less than ``1`` and :math:`y_i` is ``-infinity``, the result is ``+infinity``.
       * If :math:`x_i` is ``+infinity`` and :math:`y_i` is greater than ``0``, the result is ``+infinity``.
       * If :math:`x_i` is ``+infinity`` and :math:`y_i` is less than ``0``, the result is ``+0``.
       * If :math:`x_i` is ``-infinity``, :math:`y_i` is greater than ``0``, and :math:`y_i` is an odd integer value, the result is ``-infinity``.
       * If :math:`x_i` is ``-infinity``, :math:`y_i` is greater than ``0``, and :math:`y_i` is not an odd integer value, the result is ``+infinity``.
       * If :math:`x_i` is ``-infinity``, :math:`y_i` is less than ``0``, and :math:`y_i` is an odd integer value, the result is ``-0``.
       * If :math:`x_i` is ``-infinity``, :math:`y_i` is less than ``0``, and :math:`y_i` is not an odd integer value, the result is ``+0``.
       * If :math:`x_i` is ``+0`` and :math:`y_i` is greater than ``0``, the result is ``+0``.
       * If :math:`x_i` is ``+0`` and :math:`y_i` is less than ``0``, the result is ``+infinity``.
       * If :math:`x_i` is ``-0``, :math:`y_i` is greater than ``0``, and :math:`y_i` is an odd integer value, the result is ``-0``.
       * If :math:`x_i` is ``-0``, :math:`y_i` is greater than ``0``, and :math:`y_i` is not an odd integer value, the result is ``+0``.
       * If :math:`x_i` is ``-0``, :math:`y_i` is less than ``0``, and :math:`y_i` is an odd integer value, the result is ``-infinity``.
       * If :math:`x_i` is ``-0``, :math:`y_i` is less than ``0``, and :math:`y_i` is not an odd integer value, the result is ``+infinity``.
       * If :math:`x_i` is less than 0, :math:`x_i` is a finite number, :math:`y_i` is a finite number, and :math:`y_i` is not an integer value, the result is ``NaN``.

    Examples:
        >>> F.pow(2.0, 3.0)
        Tensor(8.0, device=xpux:0)

        Element-wise power:

        >>> x = Tensor([1, 2, 3, 4, 5])
        >>> y = Tensor([1, 2, 1, 2, 1])
        >>> F.pow(x, y)