OpenI
/
MegEngine
Not watched
1
0
Fork 0
Code
Releases 31 Wiki Activity
Issues 0 Pull Requests 0 Datasets Model Cloudbrain
You can not select more than 25 topics Topics must start with a chinese character,a letter or number, can include dashes ('-') and can be up to 35 characters long.
Tree: 60163c5d12
Branches Tags
${ item.name }
Create branch ${ searchTerm }
from '60163c5d12'
${ noResults }
MegEngine/imperative/python/megengine/functional/elemwise.py

702 lines
29 kB
Raw Blame History 

  1. # -*- coding: utf-8 -*-

  2. # MegEngine is Licensed under the Apache License, Version 2.0 (the "License")

  3. #

  4. # Copyright (c) 2014-2021 Megvii Inc. All rights reserved.

  5. #

  6. # Unless required by applicable law or agreed to in writing,

  7. # software distributed under the License is distributed on an

  8. # "AS IS" BASIS, WITHOUT ARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

  9. # pylint: disable=unused-argument,invalid-name,redefined-builtin,arguments-out-of-order

  10. import numpy as np

  11. 

  12. from ..core._imperative_rt.core2 import SymbolVar, apply

  13. from ..core.ops import builtin

  14. from ..core.ops.builtin import Elemwise

  15. from ..core.tensor.array_method import _elwise

  16. from ..core.tensor.utils import convert_inputs

  17. from ..tensor import Tensor

  18. from ..utils.deprecation import deprecated_func

  19. from .tensor_cache import get_scalar_one

  20. 

  21. __all__ = [

  22.     "abs",

  23.     "add",

  24.     "acos",

  25.     "asin",

  26.     "atan",

  27.     "atan2",

  28.     "asinh",

  29.     "acosh",

  30.     "atanh",

  31.     "ceil",

  32.     "clip",

  33.     "cos",

  34.     "cosh",

  35.     "div",

  36.     "equal",

  37.     "exp",

  38.     "expm1",

  39.     "floor",

  40.     "floor_div",

  41.     "greater",

  42.     "greater_equal",

  43.     "left_shift",

  44.     "less",

  45.     "less_equal",

  46.     "log",

  47.     "log1p",

  48.     "logical_and",

  49.     "logical_not",

  50.     "logical_or",

  51.     "logical_xor",

  52.     "logaddexp",

  53.     "maximum",

  54.     "minimum",

  55.     "mod",

  56.     "mul",

  57.     "neg",

  58.     "not_equal",

  59.     "pow",

  60.     "right_shift",

  61.     "round",

  62.     "sin",

  63.     "sinh",

  64.     "sqrt",

  65.     "square",

  66.     "sub",

  67.     "tan",

  68.     "tanh",

  69. ]

  70. 

  71. 

  72. def _elemwise_multi_type(*args, mode, **kwargs):

  73.     op = builtin.ElemwiseMultiType(mode=mode, **kwargs)

  74.     args = convert_inputs(*args)

  75.     (result,) = apply(op, *args)

  76.     return result

  77. 

  78. 

  79. # math operations

  80. 

  81. 

  82. def add(x: Tensor, y: Tensor) -> Tensor:

  83.     r"""Calculates the sum for each element :math:`x_i` of the input tensor :math:`x` with the respective element :math:`y_i` of the input tensor :math:`y`.

  84. 

  85.     Args:

  86.         x: first input tensor. Should have a numeric data type.

  87.         y: second input tensor. Must be compatible with ``x`` (see :ref:`broadcasting-rule` ). Should have a numeric data type.

  88. 

  89.     Returns:

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

  91. 

  92.     .. admonition:: Special cases

  93. 

  94.        For floating-point operands,

  95. 

  96.        * If either :math:`x` or :math:`y` is ``NaN``, the result is ``NaN``.

  97.        * If :math:`x` is ``+infinity`` and :math:`y` is ``-infinity``, the result is ``NaN``.

  98.        * If :math:`x` is ``-infinity`` and :math:`y` is ``+infinity``, the result is ``NaN``.

  99.        * If :math:`x` is ``+infinity`` and :math:`y` is ``+infinity``, the result is ``+infinity``.

  100.        * If :math:`x` is ``-infinity`` and :math:`y` is ``-infinity``, the result is ``-infinity``.

  101.        * If :math:`x` is ``+infinity`` and :math:`y` is a finite number, the result is ``+infinity``.

  102.        * If :math:`x` is ``-infinity`` and :math:`y` is a finite number, the result is ``-infinity``.

  103.        * If :math:`x` is a finite number and :math:`y` is ``+infinity``, the result is ``+infinity``.

  104.        * If :math:`x` is a finite number and :math:`y` is ``-infinity``, the result is ``-infinity``.

  105.        * If :math:`x` is ``-0`` and :math:`y` is ``-0``, the result is ``-0``.

  106.        * If :math:`x` is ``-0`` and :math:`y` is ``+0``, the result is ``+0``.

  107.        * If :math:`x` is ``+0`` and :math:`y` is ``-0``, the result is ``+0``.

  108.        * If :math:`x` is ``+0`` and :math:`y` is ``+0``, the result is ``+0``.

  109.        * If :math:`x` is either ``+0`` or ``-0`` and :math:`y` is a nonzero finite number, the result is :math:`y`.

  110.        * If :math:`x` is a nonzero finite number and :math:`y` is either ``+0`` or ``-0``, the result is :math:`x`.

  111.        * If :math:`x` is a nonzero finite number and :math:`y` is :math:`-x`, the result is ``+0``.

  112.        * In the remaining cases, when neither ``infinity``, ``+0``, ``-0``, nor a ``NaN`` is involved, 

  113.          and the operands have the same mathematical sign or have different magnitudes, 

  114.          the sum must be computed and rounded to the nearest representable value according to 

  115.          IEEE 754-2019 and a supported round mode. If the magnitude is too large to represent, 

  116.          the operation overflows and the result is an infinity of appropriate mathematical sign.

  117. 

  118.     .. note::

  119. 

  120.        * Floating-point addition is a commutative operation, but not always associative.

  121.        * The ``+`` operator can be used as a shorthand for ``add`` on tensors.

  122. 

  123.     Examples:

  124.         >>> F.add(1.0, 4.0)

  125.         Tensor(5.0, device=xpux:0)

  126.         >>> x = Tensor([[1, 2, 3], [4, 5, 6]])

  127.         >>> y = Tensor([[1, 1, 1], [2, 2, 2]])

  128.         >>> F.add(x, y)

  129.         Tensor([[2 3 4]

  130.          [6 7 8]], dtype=int32, device=xpux:0)

  131.         >>> F.add(x, 1)

  132.         Tensor([[2 3 4]

  133.          [5 6 7]], dtype=int32, device=xpux:0)

  134.     """

  135.     return _elwise(x, y, mode=Elemwise.Mode.ADD)

  136. 

  137. 

  138. def sub(x: Tensor, y: Tensor) -> Tensor:

  139.     r"""Calculates the difference for each element :math:`x_i` of the input tensor :math:`x` with the respective element :math:`y` of the input tensor :math:`y`.

  140.     The result of :math:`x_i - y_i` must be the same as :math:`x_i + (-y_i)` and must be governed by the same floating-point rules as addition.

  141.     (See :func:`~.functional.add` ).

  142. 

  143.     Args:

  144.         x: first input tensor. Should have a numeric data type.

  145.         y: second input tensor. Must be compatible with ``x`` (see :ref:`broadcasting-rule` ). Should have a numeric data type.

  146. 

  147.     Returns:

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

  149. 

  150.     .. note::

  151. 

  152.        The ``-`` operator can be used as a shorthand for ``sub`` on Tensors.

  153. 

  154.     Examples:

  155.        >>> F.sub(1.0, 4.0)

  156.        Tensor(-3.0, device=xpux:0)

  157.        >>> x = Tensor([[1, 2, 3], [4, 5, 6]])

  158.        >>> y = Tensor([[1, 1, 1], [2, 2, 2]])

  159.        >>> F.sub(x, y)

  160.        Tensor([[0 1 2]

  161.         [2 3 4]], dtype=int32, device=xpux:0)

  162.        >>> F.sub(x, 1)

  163.        Tensor([[0 1 2]

  164.         [3 4 5]], dtype=int32, device=xpux:0)

  165.     """

  166.     return _elwise(x, y, mode=Elemwise.Mode.SUB)

  167. 

  168. 

  169. def mul(x: Tensor, y: Tensor) -> Tensor:

  170.     r"""Calculates the product for each element :math:`x_i` of the input tensor `x` with the respective element :math:`y_i` of the input tensor :math:`y`.

  171. 

  172.     Args:

  173.         x: first input tensor. Should have a numeric data type.

  174.         y: second input tensor. Must be compatible with ``x`` (see :ref:`broadcasting-rule` ). Should have a numeric data type.

  175. 

  176.     Returns:

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

  178. 

  179.     .. admonition:: Special cases

  180. 

  181.        For floating-point operands,

  182. 

  183.        * If either :math:`x_i` or :math:`y_i` is ``NaN``, the result is ``NaN``.

  184.        * If :math:`x_i` is either ``+infinity`` or ``-infinity`` and :math:`y_i` is either ``+0`` or ``-0``, the result is ``NaN``.

  185.        * If :math:`x_i` is either ``+0`` or ``-0`` and :math:`y_i` is either ``+infinity`` or ``-infinity``, the result is ``NaN``.

  186.        * If :math:`x_i` and :math:`y_i` have different mathematical signs, the result has a negative mathematical sign, unless the result is ``NaN``.

  187.        * If :math:`x_i` is either ``+infinity`` or ``-infinity`` and :math:`y_i` is either ``+infinity`` or ``-infinity``,

  188.          the result is a signed infinity with the mathematical sign determined by the rule already stated above.

  189.        * If :math:`x_i` is either ``+infinity`` or ``-infinity`` and :math:`y_i` is a nonzero finite number,

  190.          the result is a signed infinity with the mathematical sign determined by the rule already stated above.

  191.        * If :math:`x_i` is a nonzero finite number and :math:`y_i` is either ``+infinity`` or ``-infinity``,

  192.          the result is a signed infinity with the mathematical sign determined by the rule already stated above.

  193.        * In the remaining cases, where neither ``infinity`` nor ``NaN`` is involved,

  194.          the product must be computed and rounded to the nearest representable value according to IEEE 754-2019 and a supported rounding mode.

  195.          If the magnitude is too large to represent, the result is an `infinity` of appropriate mathematical sign.

  196.          If the magnitude is too small to represent, the result is a zero of appropriate mathematical sign.

  197. 

  198.     .. Note::

  199. 

  200.        * Floating-point multiplication is not always associative due to finite precision.

  201.        * The ``*`` operator can be used as a shorthand for ``mul`` on tensors.

  202. 

  203.     Examples:

  204.         >>> F.mul(1.0, 4.0)

  205.         Tensor(4.0, device=xpux:0)

  206.         >>> x = Tensor([[1, 2, 3], [4, 5, 6]])

  207.         >>> y = Tensor([[1, 1, 1], [2, 2, 2]])

  208.         >>> F.mul(x, y)

  209.         Tensor([[ 1  2  3]

  210.          [ 8 10 12]], dtype=int32, device=xpux:0)

  211.         >>> F.mul(x, 2)

  212.         Tensor([[ 2  4  6]

  213.          [ 8 10 12]], dtype=int32, device=xpux:0)

  214.     """

  215.     return _elwise(x, y, mode=Elemwise.Mode.MUL)

  216. 

  217. 

  218. def div(x: Tensor, y: Tensor) -> Tensor:

  219.     r"""Calculates the division for each element :math:`x_i` of the input tensor :math:`x` with the respective element :math:`y_i` of the input tensor :math:`y`.

  220. 

  221.     Args:

  222.         x: dividend input tensor. Should have a numeric data type.

  223.         y: divisor input tensor. Must be compatible with ``x``` (see :ref:`broadcasting-rule` ). Should have a numeric data type.

  224. 

  225.     Returns:

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

  227. 

  228.     .. admonition:: Special cases

  229. 

  230.        For floating-point operands,

  231. 

  232.        * If either :math:`x` or :math:`y` is ``NaN``, the result is ``NaN``.

  233.        * If :math:`x` is either ``+infinity`` or ``-infinity`` and :math:`y` is either ``+infinity`` or ``-infinity``, the result is ``NaN``.

  234.        * If :math:`x` is either ``+0`` or ``-0`` and :math:`y` is either ``+0`` or ``-0``, the result is ``NaN``.

  235.        * If :math:`x` is ``+0`` and :math:`y` is greater than ``0``, the result is ``+0``.

  236.        * If :math:`x` is ``-0`` and :math:`y` is greater than ``0``, the result is ``-0``.

  237.        * If :math:`x` is ``+0`` and :math:`y` is less than ``0``, the result is ``-0``.

  238.        * If :math:`x` is ``-0`` and :math:`y` is less than ``0``, the result is ``+0``.

  239.        * If :math:`x` is greater than ``0`` and :math:`y` is ``+0``, the result is ``+infinity``.

  240.        * If :math:`x` is greater than ``0`` and :math:`y` is ``-0``, the result is ``-infinity``.

  241.        * If :math:`x` is less than ``0`` and :math:`y` is ``+0``, the result is ``-infinity``.

  242.        * If :math:`x` is less than ``0`` and :math:`y` is ``-0``, the result is ``+infinity``.

  243.        * If :math:`x` is ``+infinity`` and :math:`y` is a positive (i.e., greater than ``0``) finite number, the result is ``+infinity``.

  244.        * If :math:`x` is ``+infinity`` and :math:`y` is a negative (i.e., less than ``0``) finite number, the result is ``-infinity``.

  245.        * If :math:`x` is ``-infinity`` and :math:`y` is a positive (i.e., greater than ``0``) finite number, the result is ``-infinity``.

  246.        * If :math:`x` is ``-infinity`` and :math:`y` is a negative (i.e., less than ``0``) finite number, the result is ``+infinity``.

  247.        * If :math:`x` is a positive (i.e., greater than ``0``) finite number and :math:`y` is ``+infinity``, the result is ``+0``.

  248.        * If :math:`x` is a positive (i.e., greater than ``0``) finite number and :math:`y` is ``-infinity``, the result is ``-0``.

  249.        * If :math:`x` is a negative (i.e., less than ``0``) finite number and :math:`y` is ``+infinity``, the result is ``-0``.

  250.        * If :math:`x` is a negative (i.e., less than ``0``) finite number and :math:`y` is ``-infinity``, the result is ``+0``.

  251.        * If :math:`x` and :math:`y` have the same mathematical sign and are both nonzero finite numbers, the result has a positive mathematical sign.

  252.        * If :math:`x` and :math:`y` have different mathematical signs and are both nonzero finite numbers, the result has a negative mathematical sign.

  253.        * In the remaining cases, where neither ``-infinity``, ``+0``, ``-0``, nor ``NaN`` is involved, the quotient must be computed and rounded to the nearest representable value according to IEEE 754-2019 and a supported rounding mode. If the magnitude is too large to represent, the operation overflows and the result is an infinity of appropriate mathematical sign. If the magnitude is too small to represent, the operation underflows and the result is a zero of appropriate mathematical sign.

  254. 

  255.     .. note::

  256. 

  257.        The ``/`` operator can be used as a shorthand for ``div`` on tensors.

  258. 

  259.     .. seealso::

  260. 

  261.        In Python, ``//`` is the floor division operator and ``/`` is the true division operator.

  262.        See :func:`~.functional.floor_div`

  263. 

  264.     Examples:

  265.         >>> F.div(1.0, 4.0)

  266.         Tensor(0.25, device=xpux:0)

  267.         >>> x = Tensor([[1, 2, 3], [4, 5, 6]])

  268.         >>> y = Tensor([[1, 1, 1], [2, 2, 2]])

  269.         >>> F.div(x, y)

  270.         Tensor([[1.  2.  3. ]

  271.          [2.  2.5 3. ]], device=xpux:0)

  272.         >>> F.div(x, 2)

  273.         Tensor([[0.5 1.  1.5]

  274.          [2.  2.5 3. ]], device=xpux:0)

  275.     """

  276.     return _elwise(x, y, mode=Elemwise.Mode.TRUE_DIV)

  277. 

  278. 

  279. def floor_div(x: Tensor, y: Tensor) -> Tensor:

  280.     r"""Rounds the result of dividing each element :math:`x_i` of the input tensor :math:`x` 

  281.     by the respective element :math:`y_i` of the input tensor :math:`y` to the greatest 

  282.     (i.e., closest to ``+infinity``) integer-value number that is not greater than the division result.

  283. 

  284.     Args:

  285.         x: dividend input tensor. Should have a numeric data type.

  286.         y: divisor input tensor. Must be compatible with ``x``` (see :ref:`broadcasting-rule` ). Should have a numeric data type.

  287. 

  288.     Returns:

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

  290. 

  291.     .. admonition:: Special cases

  292. 

  293.        For floating-point operands,

  294. 

  295.        * If either :math:`x` or :math:`y` is ``NaN``, the result is ``NaN``.

  296.        * If :math:`x` is either ``+infinity`` or ``-infinity`` and :math:`y` is either ``+infinity`` or ``-infinity``, the result is ``NaN``.

  297.        * If :math:`x` is either ``+0`` or ``-0`` and :math:`y` is either ``+0`` or ``-0``, the result is ``NaN``.

  298.        * If :math:`x` is ``+0`` and :math:`y` is greater than ``0``, the result is ``+0``.

  299.        * If :math:`x` is ``-0`` and :math:`y` is greater than ``0``, the result is ``-0``.

  300.        * If :math:`x` is ``+0`` and :math:`y` is less than ``0``, the result is ``-0``.

  301.        * If :math:`x` is ``-0`` and :math:`y` is less than ``0``, the result is ``+0``.

  302.        * If :math:`x` is greater than ``0`` and :math:`y` is ``+0``, the result is ``+infinity``.

  303.        * If :math:`x` is greater than ``0`` and :math:`y` is ``-0``, the result is ``-infinity``.

  304.        * If :math:`x` is less than ``0`` and :math:`y` is ``+0``, the result is ``-infinity``.

  305.        * If :math:`x` is less than ``0`` and :math:`y` is ``-0``, the result is ``+infinity``.

  306.        * If :math:`x` is ``+infinity`` and :math:`y` is a positive (i.e., greater than ``0``) finite number, the result is ``+infinity``.

  307.        * If :math:`x` is ``+infinity`` and :math:`y` is a negative (i.e., less than ``0``) finite number, the result is ``-infinity``.

  308.        * If :math:`x` is ``-infinity`` and :math:`y` is a positive (i.e., greater than ``0``) finite number, the result is ``-infinity``.

  309.        * If :math:`x` is ``-infinity`` and :math:`y` is a negative (i.e., less than ``0``) finite number, the result is ``+infinity``.

  310.        * If :math:`x` is a positive (i.e., greater than ``0``) finite number and :math:`y` is ``+infinity``, the result is ``+0``.

  311.        * If :math:`x` is a positive (i.e., greater than ``0``) finite number and :math:`y` is ``-infinity``, the result is ``-0``.

  312.        * If :math:`x` is a negative (i.e., less than ``0``) finite number and :math:`y` is ``+infinity``, the result is ``-0``.

  313.        * If :math:`x` is a negative (i.e., less than ``0``) finite number and :math:`y` is ``-infinity``, the result is ``+0``.

  314.        * If :math:`x` and :math:`y` have the same mathematical sign and are both nonzero finite numbers, the result has a positive mathematical sign.

  315.        * If :math:`x` and :math:`y` have different mathematical signs and are both nonzero finite numbers, the result has a negative mathematical sign.

  316.        * In the remaining cases, where neither ``-infinity``, ``+0``, ``-0``, nor ``NaN`` is involved, the quotient must be computed and rounded to the nearest representable value according to IEEE 754-2019 and a supported rounding mode. If the magnitude is too large to represent, the operation overflows and the result is an infinity of appropriate mathematical sign. If the magnitude is too small to represent, the operation underflows and the result is a zero of appropriate mathematical sign.

  317. 

  318.     .. note::

  319. 

  320.        The ``//`` operator can be used as a shorthand for ``floor_div`` on tensors.

  321. 

  322.     .. seealso::

  323. 

  324.        In Python, ``//`` is the floor division operator and ``/`` is the true division operator.

  325.        See :func:`~.functional.div`

  326. 

  327.     Examples:

  328.        >>> F.floor_div(5.0, 4.0)

  329.        Tensor(1.0, device=xpux:0)

  330.        >>> x = Tensor([[1, 2, 3], [4, 5, 6]])

  331.        >>> y = Tensor([[1, 1, 1], [2, 2, 2]])

  332.        >>> F.floor_div(x, y)

  333.        Tensor([[1 2 3]

  334.         [2 2 3]], dtype=int32, device=xpux:0)

  335.        >>> F.floor_div(x, 2)

  336.        Tensor([[0 1 1]

  337.         [2 2 3]], dtype=int32, device=xpux:0)

  338.     """

  339.     return _elwise(x, y, mode=Elemwise.Mode.FLOOR_DIV)

  340. 

  341. 

  342. def neg(x: Tensor) -> Tensor:

  343.     r"""Computes the numerical negative of each element :math:`x_i` (i.e., :math:`y_i = -x_i` ) of the input tensor :math:`x`.

  344. 

  345.     Args:

  346.         x: input tensor. Should have a numeric data type.

  347. 

  348.     Returns:

  349.         A tensor containing the evaluated result for each element in :math:`x`.

  350.         The returned tensor must have a data type determined by :ref:`dtype-promotion`.

  351. 

  352.     .. note::

  353. 

  354.        The unary ``-`` operator can be used as a shorthand for ``neg`` on tensors.

  355. 

  356.     Examples:

  357.        >>> x = Tensor([1, -1])

  358.        >>> F.neg(x)

  359.        Tensor([-1  1], dtype=int32, device=xpux:0)

  360.     """

  361.     return _elwise(x, mode=Elemwise.Mode.NEGATE)

  362. 

  363. 

  364. def pow(x: Tensor, y: Tensor) -> Tensor:

  365.     r"""Calculates an implementation-dependent approximation of exponentiation by 

  366.     raising each element :math:`x_i` (the base) of the input tensor :math:`x` to 

  367.     the power of :math:`y_i` (the exponent), where :math:`y_i` is the corresponding element of the input tensor :math:`y`.

  368. 

  369.     Args:

  370.         x: first input tensor whose elements correspond to the exponentiation base. Should have a numeric data type.

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

  372. 

  373.     Returns:

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

  375. 

  376.     .. note::

  377. 

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

  379. 

  380.     .. admonition:: Special cases

  381. 

  382.        For floating-point operands,

  383. 

  384.        * If :math:`x_i` is not equal to ``1`` and :math:`y_i` is ``NaN``, the result is ``NaN``.

  385.        * If :math:`y_i` is ``+0``, the result is ``1``, even if ``x_i`` is ``NaN``.

  386.        * If :math:`y_i` is ``-0``, the result is ``1``, even if ``x_i`` is ``NaN``.

  387.        * If :math:`x_i` is ``NaN`` and ``y_i`` is not equal to ``0``, the result is ``NaN``.

  388.        * If ``abs(x_i)`` is greater than ``1`` and ``y_i`` is ``+infinity``, the result is ``+infinity``.

  389.        * If ``abs(x_i)`` is greater than ``1`` and ``y_i`` is ``-infinity``, the result is ``+0``.

  390.        * If ``abs(x_i)`` is ``1`` and ``y_i`` is ``+infinity``, the result is ``1``.

  391.        * If ``abs(x_i)`` is ``1`` and ``y_i`` is ``-infinity``, the result is ``1``.

  392.        * If ``x_i`` is ``1`` and ``y_i`` is not ``NaN``, the result is ``1``.

  393.        * If ``abs(x_i)`` is less than ``1`` and ``y_i`` is ``+infinity``, the result is ``+0``.

  394.        * If ``abs(x_i)`` is less than ``1`` and ``y_i`` is ``-infinity``, the result is ``+infinity``.

  395.        * If ``x_i`` is ``+infinity`` and ``y_i`` is greater than 0, the result is ``+infinity``.

  396.        * If ``x_i`` is ``+infinity`` and ``y_i`` is less than 0, the result is ``+0``.

  397.        * If ``x_i`` is ``-infinity``, ``y_i`` is greater than 0, and ``y_i`` is an odd integer value, the result is ``-infinity``.

  398.        * If ``x_i`` is ``-infinity``, ``y_i`` is greater than 0, and ``y_i`` is not an odd integer value, the result is ``+infinity``.

  399.        * If ``x_i`` is ``-infinity``, ``y_i`` is less than 0, and ``y_i`` is an odd integer value, the result is ``-0``.

  400.        * If ``x_i`` is ``-infinity``, ``y_i`` is less than 0, and ``y_i`` is not an odd integer value, the result is ``+0``.

  401.        * If ``x_i`` is ``+0`` and ``y_i`` is greater than 0, the result is ``+0``.

  402.        * If ``x_i`` is ``+0`` and ``y_i`` is less than 0, the result is ``+infinity``.

  403.        * If ``x_i`` is ``-0``, ``y_i`` is greater than 0, and ``y_i`` is an odd integer value, the result is ``-0``.

  404.        * If ``x_i`` is ``-0``, ``y_i`` is greater than 0, and ``y_i`` is not an odd integer value, the result is ``+0``.

  405.        * If ``x_i`` is ``-0``, ``y_i`` is less than 0, and ``y_i`` is an odd integer value, the result is ``-infinity``.

  406.        * If ``x_i`` is ``-0``, ``y_i`` is less than 0, and ``y_i`` is not an odd integer value, the result is ``+infinity``.

  407.        * If ``x_i`` is less than 0, ``x_i`` is a finite number, ``y_i`` is a finite number, and ``y_i`` is not an integer value, the result is ``NaN``.

  408. 

  409.     Examples:

  410.         >>> F.pow(2.0, 3.0)

  411.         Tensor(8.0, device=xpux:0)

  412.         >>> x = Tensor([1, 2, 3, 4, 5])

  413.         >>> y = Tensor([1, 2, 1, 2, 1])

  414.         >>> F.pow(x, y)

  415.         Tensor([ 1.  4.  3. 16.  5.], device=xpux:0)

  416.         >>> F.pow(x, 2)

  417.         Tensor([ 1.  4.  9. 16. 25.], device=xpux:0)

  418.     """

  419.     return _elwise(x, y, mode=Elemwise.Mode.POW)

  420. 

  421. 

  422. def mod(x: Tensor, y: Tensor) -> Tensor:

  423.     r"""Returns the remainder of division for each element ``x_i`` of the input tensor ``x``

  424.     and the respective element ``y_i`` of the input tensor ``y``.

  425. 

  426.     .. note:: ``mod`` is an alias of ``remainder`` in NumPy.

  427. 

  428.     .. seealso:: :func:`~.div` / :func:`~.floor_div`

  429. 

  430.     Args:

  431.         x: dividend input tensor. Should have a numeric data type.

  432.         y: divisor input tensor. Must be compatible with ``x`` (see :ref:`broadcasting-rule` ). Should have a numeric data type.

  433. 

  434.     Returns:

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

  436. 

  437.     Examples:

  438.         >>> F.mod(8, 3)

  439.         Tensor(2, dtype=int32, device=xpux:0)

  440.         >>> x = Tensor([1, 2, 3, 4, 5])

  441.         >>> y = Tensor([1, 2, 1, 2, 1])

  442.         >>> F.mod(x, y)

  443.         Tensor([0 0 0 0 0], dtype=int32, device=xpux:0)

  444.         >>> F.mod(x, 3)

  445.         Tensor([1 2 0 1 2], dtype=int32, device=xpux:0)

  446.     """

  447.     return _elwise(x, y, mode=Elemwise.Mode.MOD)

  448. 

  449. 

  450. def abs(x):

  451.     r"""Element-wise `absolute value`."""

  452.     return _elwise(x, mode=Elemwise.Mode.ABS)

  453. 

  454. 

  455. def exp(x):

  456.     r"""Element-wise `exponential`."""

  457.     return _elwise(x, mode=Elemwise.Mode.EXP)

  458. 

  459. 

  460. def expm1(x):

  461.     r"""Element-wise `exp(x)-1`."""

  462.     return _elwise(x, mode=Elemwise.Mode.EXPM1)

  463. 

  464. 

  465. def log(x):

  466.     r"""Element-wise `logarithm (base e)`."""

  467.     return _elwise(x, mode=Elemwise.Mode.LOG)

  468. 

  469. 

  470. def log1p(x):

  471.     r"""Element-wise `log(x+1) (base e)`."""

  472.     return _elwise(x, mode=Elemwise.Mode.LOG1P)

  473. 

  474. 

  475. def sqrt(x: Tensor) -> Tensor:

  476.     r"""Element-wise `sqrt`."""

  477.     return x ** 0.5

  478. 

  479. 

  480. def square(x: Tensor) -> Tensor:

  481.     r"""Element-wise `square`."""

  482.     return x ** 2

  483. 

  484. 

  485. def round(x):

  486.     r"""Element-wise `rounding to int`."""

  487.     return _elwise(x, mode=Elemwise.Mode.ROUND)

  488. 

  489. 

  490. def ceil(x):

  491.     r"""Element-wise `ceiling`."""

  492.     return _elwise(x, mode=Elemwise.Mode.CEIL)

  493. 

  494. 

  495. def floor(x):

  496.     r"""Element-wise `floor`."""

  497.     return _elwise(x, mode=Elemwise.Mode.FLOOR)

  498. 

  499. 

  500. def maximum(x, y):

  501.     r"""Element-wise `maximum of array elements`."""

  502.     return _elwise(x, y, mode=Elemwise.Mode.MAX)

  503. 

  504. 

  505. def minimum(x, y):

  506.     r"""Element-wise `minimum of array elements`."""

  507.     return _elwise(x, y, mode=Elemwise.Mode.MIN)

  508. 

  509. 

  510. # trigonometric functions

  511. 

  512. 

  513. def cos(x):

  514.     r"""Element-wise `cosine`."""

  515.     return _elwise(x, mode=Elemwise.Mode.COS)

  516. 

  517. 

  518. def sin(x):

  519.     r"""Element-wise `sine`."""

  520.     return _elwise(x, mode=Elemwise.Mode.SIN)

  521. 

  522. 

  523. def tan(x):

  524.     r"""Element-wise `tangent`."""

  525.     return sin(x) / cos(x)

  526. 

  527. 

  528. def acos(x):

  529.     r"""Element-wise `inverse cosine`."""

  530.     return _elwise(x, mode=Elemwise.Mode.ACOS)

  531. 

  532. 

  533. def asin(x):

  534.     r"""Element-wise `inverse sine`."""

  535.     return _elwise(x, mode=Elemwise.Mode.ASIN)

  536. 

  537. 

  538. def atan(x):

  539.     r"""Element-wise `inverse tangent`."""

  540.     return _elwise(

  541.         x,

  542.         get_scalar_one("float32", x.device if isinstance(x, Tensor) else None),

  543.         mode=Elemwise.Mode.ATAN2,

  544.     )

  545. 

  546. 

  547. def atan2(y, x):

  548.     r"""Element-wise `2-argument arctangent`."""

  549.     return _elwise(y, x, mode=Elemwise.Mode.ATAN2)

  550. 

  551. 

  552. def cosh(x):

  553.     r"""Element-wise `hyperbolic cosine`."""

  554.     return 0.5 * (exp(x) + exp(-x))

  555. 

  556. 

  557. def sinh(x):

  558.     r"""Element-wise `hyperbolic sine`."""

  559.     u = expm1(x)

  560.     return 0.5 * u / (u + 1) * (u + 2)

  561. 

  562. 

  563. def tanh(x):

  564.     r"""Element-wise `hyperbolic tangent`."""

  565.     return _elwise(x, mode=Elemwise.Mode.TANH)

  566. 

  567. 

  568. def asinh(x):

  569.     r"""Element-wise `inverse hyperbolic sine`."""

  570.     return log(x + (x ** 2 + 1) ** 0.5)

  571. 

  572. 

  573. def acosh(x):

  574.     r"""Element-wise `inverse hyperbolic cosine`."""

  575.     return log(x + (x ** 2 - 1) ** 0.5)

  576. 

  577. 

  578. def atanh(x):

  579.     r"""Element-wise `inverse hyperbolic tangent`."""

  580.     return log1p(2 * x / (1 - x)) / 2

  581. 

  582. 

  583. # bit-twiddling functions

  584. 

  585. 

  586. def left_shift(x, y):

  587.     r"""Element-wise `bitwise binary: x << y`."""

  588.     return _elwise(x, y, mode=Elemwise.Mode.SHL)

  589. 

  590. 

  591. def right_shift(x, y):

  592.     r"""Element-wise `bitwise binary: x >> y`."""

  593.     return _elwise(x, y, mode=Elemwise.Mode.SHR)

  594. 

  595. 

  596. # logical functions

  597. 

  598. 

  599. def logical_and(x, y):

  600.     r"""Element-wise `logical and: x && y`."""

  601.     return _elwise(x, y, mode=Elemwise.Mode.AND)

  602. 

  603. 

  604. def logical_not(x):

  605.     r"""Element-wise `logical not: ~x`."""

  606.     return _elwise(x, mode=Elemwise.Mode.NOT)

  607. 

  608. 

  609. def logical_or(x, y):

  610.     r"""Element-wise `logical or: x || y`."""

  611.     return _elwise(x, y, mode=Elemwise.Mode.OR)

  612. 

  613. 

  614. def logical_xor(x, y):

  615.     r"""Element-wise `logical xor: x ^ y`."""

  616.     return _elwise(x, y, mode=Elemwise.Mode.XOR)

  617. 

  618. 

  619. def logaddexp(x: Tensor, y: Tensor) -> Tensor:

  620.     r"""Element-wise `numerically stable log(exp(x) + exp(y)`."""

  621.     return _elwise(x, y, mode=Elemwise.Mode.LOG_SUM_EXP)

  622. 

  623. 

  624. # comparison functions

  625. 

  626. 

  627. def equal(x, y):

  628.     r"""Element-wise `(x == y)`."""

  629.     return _elwise(x, y, mode=Elemwise.Mode.EQ)

  630. 

  631. 

  632. def not_equal(x, y):

  633.     r"""Element-wise `(x != y)`."""

  634.     return x != y

  635. 

  636. 

  637. def less(x, y):

  638.     r"""Element-wise `(x < y)`."""

  639.     return _elwise(x, y, mode=Elemwise.Mode.LT)

  640. 

  641. 

  642. def less_equal(x, y):

  643.     r"""Element-wise `(x <= y)`."""

  644.     return _elwise(x, y, mode=Elemwise.Mode.LEQ)

  645. 

  646. 

  647. def greater(x, y):

  648.     r"""Element-wise `(x > y)`."""

  649.     return _elwise(y, x, mode=Elemwise.Mode.LT)

  650. 

  651. 

  652. def greater_equal(x, y):

  653.     r"""Element-wise `(x >= y)`."""

  654.     return _elwise(y, x, mode=Elemwise.Mode.LEQ)

  655. 

  656. 

  657. # other functions

  658. 

  659. 

  660. def clip(x: Tensor, lower=None, upper=None) -> Tensor:

  661.     r"""Clamps all elements in input tensor into the range ``[ lower, upper ]`` and returns

  662.     a resulting tensor:

  663. 

  664.     .. math::

  665. 

  666.         y_i = \begin{cases}

  667.             \text{lower} & \text{if } x_i < \text{lower} \\

  668.             x_i & \text{if } \text{lower} \leq x_i \leq \text{upper} \\

  669.             \text{upper} & \text{if } x_i > \text{upper}

  670.         \end{cases}

  671. 

  672.     Args:

  673.         x: (Tensor): The input tensor.

  674.         lower: (Numberic，optional): lower-bound of the range to be clamped to.

  675.         upper: (Numberic，optional): upper-bound of the range to be clamped to.        

  676. 

  677.     Note:

  678.         * If both `lower` and `upper` are None, raises an AssertionError.

  679.         * If `lower` is bigger than `upper`, the result is same as `clip(Tensor(), upper, upper)`.

  680. 

  681.     Returns:

  682.         output clamped tensor. The result must have a data type determined by :ref:`dtype-promotion`.

  683. 

  684.     """

  685.     assert (

  686.         lower is not None or upper is not None

  687.     ), "At least one of 'lower' or 'upper' must not be None"

  688.     if lower is not None:

  689.         if upper is not None:

  690.             return minimum(maximum(x, lower), upper)

  691.         else:

  692.             return maximum(x, lower)

  693.     else:

  694.         return minimum(x, upper)

  695. 

  696. 

  697. sigmoid = deprecated_func("1.3", "megengine.functional.nn", "sigmoid", True)

  698. hsigmoid = deprecated_func("1.3", "megengine.functional.nn", "hsigmoid", True)

  699. relu = deprecated_func("1.3", "megengine.functional.nn", "relu", True)

  700. relu6 = deprecated_func("1.3", "megengine.functional.nn", "relu6", True)

  701. hswish = deprecated_func("1.3", "megengine.functional.nn", "hswish", True)