From 5f84d29160924b1aa7ccf0f427b5a76a51a51b16 Mon Sep 17 00:00:00 2001 From: Enigmatisms Date: Mon, 25 Aug 2025 08:11:50 +0000 Subject: [PATCH] [API-Compat] Fix doc & decorator warn & add min/max warning --- python/paddle/tensor/compat.py | 20 ++++++++++++-------- python/paddle/tensor/math.py | 2 ++ python/paddle/utils/decorator_utils.py | 1 + 3 files changed, 15 insertions(+), 8 deletions(-) diff --git a/python/paddle/tensor/compat.py b/python/paddle/tensor/compat.py index 11687bc9474899..48b0326b532fe2 100644 --- a/python/paddle/tensor/compat.py +++ b/python/paddle/tensor/compat.py @@ -545,12 +545,14 @@ def min( """ Computes the minimum of tensor elements. There are mainly 3 cases (functionalities): + 1. paddle.compat.min(input: Tensor): reduce min over all dims, return a single value Tensor 2. paddle.compat.min(input: Tensor, dim: int (cannot be None), keepdim=False): reduce min over the given dim, returns a named tuple MinMaxRetType(values: Tensor, indices: Tensor) 3. paddle.compat.min(input: Tensor, other: Tensor): see `paddle.minimum` Special warning: the gradient behavior is NOT well-documented by PyTorch, the actual behavior should be: + 1. Case 1: the same as `min` 2. Case 2: NOT evenly distributing the gradient for equal minimum elements! PyTorch actually only propagates to the elements with indices, for example: Tensor([1, 1, 1]) -> min(..., dim=0) -> values=Tensor(0, ...), indices=Tensor(0), the gradient for input tensor won't be @@ -570,7 +572,7 @@ def min( keepdim (bool, optional): Whether to reserve the reduced dimension in the output Tensor. The result tensor will have one fewer dimension than the `input` unless :attr:`keepdim` is true, default - value is False. Note that if `dim` does not appear in neither (*args) or (**kwargs), this parameter cannot be passed alone + value is False. Note that if `dim` does not appear in neither (`*args`) or (`**kwargs`), this parameter cannot be passed alone other (Tensor, optional): the other tensor to perform `paddle.minimum` with. This Tensor should have the same or broadcast-able shape as the `input`. Note that (`dim` & `keepdim`) and `other` are mutually exclusive meaning that trying to composite both will result in TypeError @@ -579,11 +581,11 @@ def min( Returns: - - For case 1: a single value Tensor (0-dim) - - For case 2: a named tuple MinMaxRetType(values: Tensor, indices: Tensor), `values` has the same data type as the `input`, + - For case 1. A single value Tensor (0-dim) + - For case 2. A named tuple MinMaxRetType(values: Tensor, indices: Tensor), `values` has the same data type as the `input`, while indices is always an int64 Tensor, with exactly the same shape as `values`. MinMaxRetType can be used (indexed, packed, unpacked) in the same way as a regular tuple - - For case 3: see `paddle.minimum` + - For case 3. See `paddle.minimum` (:ref:`api_paddle_minimum`) Examples: @@ -697,12 +699,14 @@ def max( """ Computes the maximum of tensor elements. There are mainly 3 cases (functionalities): + 1. paddle.compat.max(input: Tensor): reduce max over all dims, return a single value Tensor 2. paddle.compat.max(input: Tensor, dim: int (cannot be None), keepdim=False): reduce max over the given dim, returns a named tuple MinMaxRetType(values: Tensor, indices: Tensor) 3. paddle.compat.max(input: Tensor, other: Tensor): see `paddle.maximum` Special warning: the gradient behavior is NOT well-documented by PyTorch, the actual behavior should be: + 1. Case 1: the same as `max` 2. Case 2: NOT evenly distributing the gradient for equal maximum elements! PyTorch actually only propagates to the elements with indices, for example: Tensor([1, 1, 1]) -> max(..., dim=0) -> values=Tensor(0, ...), indices=Tensor(0), the gradient for input tensor won't be @@ -722,7 +726,7 @@ def max( keepdim (bool, optional): Whether to reserve the reduced dimension in the output Tensor. The result tensor will have one fewer dimension than the `input` unless :attr:`keepdim` is true, default - value is False. Note that if `dim` does not appear in neither (*args) or (**kwargs), this parameter cannot be passed alone + value is False. Note that if `dim` does not appear in neither (`*args`) or (`**kwargs`), this parameter cannot be passed alone other (Tensor, optional): the other tensor to perform `paddle.maximum` with. This Tensor should have the same or broadcast-able shape as the `input`. Note that (`dim` & `keepdim`) and `other` are mutually exclusive meaning that trying to composite both will result in TypeError @@ -731,11 +735,11 @@ def max( Returns: - - For case 1: a single value Tensor (0-dim) - - For case 2: a named tuple MinMaxRetType(values: Tensor, indices: Tensor), `values` has the same data type as the `input`, + - For case 1. A single value Tensor (0-dim) + - For case 2. A named tuple MinMaxRetType(values: Tensor, indices: Tensor), `values` has the same data type as the `input`, while indices is always an int64 Tensor, with exactly the same shape as `values`. MinMaxRetType can be used (indexed, packed, unpacked) in the same way as a regular tuple - - For case 3: see `paddle.maximum` + - For case 3. See `paddle.maximum` (:ref:`api_paddle_maximum`) Examples: diff --git a/python/paddle/tensor/math.py b/python/paddle/tensor/math.py index ce5c4f93ce8049..033cd289f5bde9 100644 --- a/python/paddle/tensor/math.py +++ b/python/paddle/tensor/math.py @@ -3306,6 +3306,7 @@ def _check_input(x): illegal_keys={"input", "dim", "other"}, func_name="paddle.max", correct_name="paddle.compat.max", + url_suffix="torch/torch.max", ) def max( x: Tensor, @@ -3470,6 +3471,7 @@ def max( illegal_keys={"input", "dim", "other"}, func_name="paddle.min", correct_name="paddle.compat.min", + url_suffix="torch/torch.min", ) def min( x: Tensor, diff --git a/python/paddle/utils/decorator_utils.py b/python/paddle/utils/decorator_utils.py index e4a8b0a730b2aa..4a26844dc0da3e 100644 --- a/python/paddle/utils/decorator_utils.py +++ b/python/paddle/utils/decorator_utils.py @@ -399,6 +399,7 @@ def process( self.warn_msg, category=Warning, ) + self.warn_msg = None return args, kwargs