Function clip

imperative/python/megengine/functional/elemwise.py:1041–1082

r"""Element-wise clipping function. Clamps(limits) all elements :math:`x_i` of the input tensor :math:`x` into the range ``[ lower, upper ]``. For example, if a range of ``[0, 1]`` is specified, values smaller than ``0`` become ``0``, and values larger than ``1`` become ``1``.

(x: Tensor, lower=None, upper=None)

def clip(x: Tensor, lower=None, upper=None) -> Tensor:
    r"""Element-wise clipping function.
    
    Clamps(limits) all elements :math:`x_i` of the input tensor :math:`x` into the range ``[ lower, upper ]``.
    For example, if a range of ``[0, 1]`` is specified, 
    values smaller than ``0`` become ``0``, and values larger than ``1`` become ``1``.

    .. math::

        y_i = \begin{cases}
            \text{lower} & \text{if } x_i < \text{lower} \\
            x_i & \text{if } \text{lower} \leq x_i \leq \text{upper} \\
            \text{upper} & \text{if } x_i > \text{upper}
        \end{cases}

    Equivalent to ``F.minimum(upper, np.maximum(x, upper))`` right now.

    Args:
        x: The input tensor.
        lower: lower-bound of the range to be clamped to. Should have a numeric data type.
        upper: upper-bound of the range to be clamped to. Should have a numeric data type.

    Note:
        * If both ``lower`` and ``upper`` are None, raises an ``AssertionError``.
        * If ``lower`` is None, equivalent to ``F.minimum(x, upper)``.
        * If ``upper`` is None, equivalent to ``F.maximum(x, lower)``.
        * If ``lower`` is bigger than ```upper``, the result is same as ``clip(Tensor(), upper, upper)``.

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

    """
    assert (
        lower is not None or upper is not None
    ), "At least one of 'lower' or 'upper' must not be None"
    if lower is not None:
        if upper is not None:
            return _elwise(x, lower, upper, mode=Elemwise.Mode.CLIP)
        else:
            return maximum(x, lower)
    else:
        return minimum(x, upper)


# trigonometric functions