[API Compatiblity] Support paddle.unflatten and add paddle.nn.functional.unfold (PaddlePaddle#76493)

fangfangssj · web-flow · commit 34ebd2d8548c · 2025-11-24T15:41:38.000+08:00
* add unfold

* remove

* fix UT

* fix doc
diff --git a/python/paddle/compat/nn/__init__.py b/python/paddle/compat/nn/__init__.py
@@ -21,9 +21,6 @@
 
 import paddle
 from paddle import nn
-from paddle.framework import (
-    in_dynamic_mode,
-)
 from paddle.utils.decorator_utils import ForbidKeywordsDecorator
 
 from . import functional
@@ -458,28 +455,16 @@ def __init__(
         super().__init__(kernel_size, dilation, padding, stride)
 
     def forward(self, input: Tensor) -> Tensor:
-        def to_list_if_necessary(x, size_check=False):
-            res = x
-            if in_dynamic_mode() and isinstance(
-                x, (paddle.pir.Value, paddle.Tensor)
-            ):
-                res = x.tolist()
-            else:
-                if not isinstance(x, (list, tuple, int)):
-                    raise TypeError(
-                        "paddle.compat.nn.Unfold does not allow paddle.Tensor or pir.Value as inputs in static graph mode."
-                    )
-            if size_check and isinstance(res, (list, tuple)) and len(res) > 2:
-                raise ValueError(
-                    f"The `padding` field of paddle.compat.nn.Unfold can only have size 1 or 2, now len={len(res)}. \nDid you mean to use paddle.nn.Unfold() instead?"
-                )
-            return res
+        def to_list_if_necessary(x):
+            if isinstance(x, (paddle.pir.Value, paddle.Tensor)):
+                x = x.tolist()
+            return x
 
         return nn.functional.unfold(
             input,
             kernel_sizes=to_list_if_necessary(self.kernel_sizes),
             strides=to_list_if_necessary(self.strides),
-            paddings=to_list_if_necessary(self.paddings, size_check=True),
+            paddings=to_list_if_necessary(self.paddings),
             dilations=to_list_if_necessary(self.dilations),
             name=self.name,
         )
diff --git a/python/paddle/compat/nn/functional/__init__.py b/python/paddle/compat/nn/functional/__init__.py
@@ -31,14 +31,15 @@
     from paddle import Tensor
     from paddle._typing import (
         ShapeLike,
+        Size2,
     )
 
     _PaddingTensorMode: TypeAlias = Literal[
         "zeros", "constant", "reflect", "replicate", "circular"
     ]
 
 
-__all__ = ['pad', 'softmax', 'linear']
+__all__ = ['pad', 'softmax', 'linear', 'unfold']
 
 
 def _check_valid_pad_len(pad_len, x_dim, is_constant):
@@ -266,3 +267,95 @@ def linear(input: Tensor, weight: Tensor, bias: Tensor | None = None) -> Tensor:
     if bias is not None:
         out = _C_ops.add(out, bias)
     return out
+
+
+@ForbidKeywordsDecorator(
+    illegal_keys={
+        "x",
+        "kernel_sizes",
+        "dilations",
+        "paddings",
+        "strides",
+        "name",
+    },
+    func_name="paddle.compat.nn.functional.unfold",
+    correct_name="paddle.nn.functional.unfold",
+)
+def unfold(
+    input: Tensor,
+    kernel_size: Size2,
+    dilation: Size2 = 1,
+    padding: Size2 = 0,
+    stride: Size2 = 1,
+) -> Tensor:
+    r"""
+
+    Return a col buffer of sliding local blocks of input, also known
+    as im2col for batched 2D image tensors. For each block under the convolution filter,
+    all element will be rearranged as a column. While the convolution filter sliding over
+    the input feature map, a series of such columns will be formed.
+
+    For each input :math:`input` with shape [N, C, H, W], the output shape [N, Cout, Lout]
+    can be calculated as following.
+
+    .. math::
+
+        dkernel[0] &= dilation[0] \times (kernel\_sizes[0] - 1) + 1
+
+        dkernel[1] &= dilation[1] \times (kernel\_sizes[1] - 1) + 1
+
+        hout &= \frac{H + padding[0] + padding[2] - dkernel[0]}{stride[0]} + 1
+
+        wout &= \frac{W + padding[1] + padding[3] - dkernel[1]}{stride[1]} + 1
+
+        Cout &= C \times kernel\_sizes[0] \times kernel\_sizes[1]
+
+        Lout &= hout \times wout
+
+
+    Parameters:
+        input(Tensor):              4-D Tensor, input tensor of format [N, C, H, W],
+                                  data type can be float32 or float64
+        kernel_size(int|list|tuple):   The size of convolution kernel, should be [k_h, k_w]
+                                  or an integer k treated as [k, k].
+        dilation(int|list|tuple, optional):      the dilation of convolution kernel, should be
+                                  [dilation_h, dilation_w], or an integer dilation treated as
+                                  [dilation, dilation]. For default, it will be [1, 1].
+        padding(int|list|tuple, optional):       The paddings of each dimension, should be
+                                    a single integer or [padding_h, padding_w]. If [padding_h, padding_w] was given, it will expanded to
+                                    [padding_h, padding_w, padding_h, padding_w]. If an integer padding was given,
+                                    [padding, padding, padding, padding] will be used. By default, paddings will be 0.
+        strides(int|list|tuple, optional):        The strides, should be [stride_h, stride_w]
+                                  or an integer stride treated as [stride, stride].
+                                  For default, strides will be [1, 1].
+
+    Returns:
+        Tensor, The tensor corresponding to the sliding local blocks.
+        The output shape is [N, Cout, Lout] as described above.
+        Cout is the  total number of values within each block,
+        and Lout is the total number of such blocks.
+        The data type of output is the same as the input :math:`input`
+
+    Examples:
+
+        .. code-block:: python
+
+            >>> import paddle
+            >>> import paddle.compat.nn.functional as F
+
+            >>> x = paddle.randn((100,3,224,224))
+            >>> y = F.unfold(x, [3, 3], 1, 1, 1)
+    """
+
+    def to_list_if_necessary(x):
+        if isinstance(x, (paddle.pir.Value, paddle.Tensor)):
+            x = x.tolist()
+        return x
+
+    return paddle.nn.functional.unfold(
+        x=input,
+        kernel_sizes=to_list_if_necessary(kernel_size),
+        strides=to_list_if_necessary(stride),
+        paddings=to_list_if_necessary(padding),
+        dilations=to_list_if_necessary(dilation),
+    )
diff --git a/python/paddle/tensor/manipulation.py b/python/paddle/tensor/manipulation.py
@@ -7705,6 +7705,7 @@ def index_add_(
     return _C_ops.index_add_(x, index, scaled_value, axis)
 
 
+@ParamAliasDecorator({"x": ["input"], "axis": ["dim"], "shape": ["sizes"]})
 def unflatten(
     x: Tensor, axis: int, shape: ShapeLike, name: str | None = None
 ) -> Tensor:
@@ -7718,13 +7719,21 @@ def unflatten(
        :alt: Illustration of unflatten
        :align: center
 
+    .. note::
+        Alias Support: The parameter name ``input`` can be used as an alias for ``x``.
+        Alias Support: The parameter name ``dim`` can be used as an alias for ``axis``.
+        Alias Support: The parameter name ``sizes`` can be used as an alias for ``shape``.
+
     Args:
         x (Tensor) : An N-D Tensor. The data type is float16, float32, float64, int16, int32, int64, bool, uint16.
+            Alias: ``input``.
         axis (int): :attr:`axis` to be unflattened, specified as an index into `x.shape`.
+            Alias: ``dim``.
         shape (list|tuple|Tensor): Unflatten :attr:`shape` on the specified :attr:`axis`. At most one dimension of the target :attr:`shape` can be -1.
             If the input :attr:`shape` does not contain -1 , the product of all elements in ``shape`` should be equal to ``x.shape[axis]``.
             The data type is `int` . If :attr:`shape` is a list or tuple, the elements of it should be integers or Tensors with shape [].
             If :attr:`shape` is an Tensor, it should be an 1-D Tensor.
+            Alias: ``sizes``.
         name(str|None, optional): For details, please refer to :ref:`api_guide_Name`. Generally, no setting is required. Default: None.
 
     Returns:
@@ -7740,21 +7749,21 @@ def unflatten(
             >>> axis = 1
             >>> res = paddle.unflatten(x, axis, shape)
             >>> print(res.shape)
-            [4, 2, 3, 8]
+            paddle.Size([4, 2, 3, 8])
 
             >>> x = paddle.randn(shape=[4, 6, 8])
             >>> shape = (-1, 2)
             >>> axis = -1
             >>> res = paddle.unflatten(x, axis, shape)
             >>> print(res.shape)
-            [4, 6, 4, 2]
+            paddle.Size([4, 6, 4, 2])
 
             >>> x = paddle.randn(shape=[4, 6, 8])
             >>> shape = paddle.to_tensor([2, 2])
             >>> axis = 0
             >>> res = paddle.unflatten(x, axis, shape)
             >>> print(res.shape)
-            [2, 2, 6, 8]
+            paddle.Size([2, 2, 6, 8])
     """
 
     # determine whether the input axis is valid.
diff --git a/test/legacy_test/test_compat_unfold.py b/test/legacy_test/test_compat_unfold.py
@@ -14,9 +14,9 @@
 import unittest
 
 import numpy as np
-from op_test import get_device_place, is_custom_device
 
 import paddle
+import paddle.compat.nn.functional as F_compat
 
 
 class TestCompatUnfold(unittest.TestCase):
@@ -77,8 +77,6 @@ def test_error_handling(self):
 
         msg_gt_1 = "paddle.nn.Unfold() received unexpected keyword arguments 'dilation', 'stride'. \nDid you mean to use paddle.compat.nn.Unfold() instead?"
         msg_gt_2 = "paddle.compat.nn.Unfold() received unexpected keyword argument 'paddings'. \nDid you mean to use paddle.nn.Unfold() instead?"
-        msg_gt_3 = "The `padding` field of paddle.compat.nn.Unfold can only have size 1 or 2, now len=4. \nDid you mean to use paddle.nn.Unfold() instead?"
-        msg_gt_4 = "paddle.compat.nn.Unfold does not allow paddle.Tensor or pir.Value as inputs in static graph mode."
 
         with self.assertRaises(TypeError) as cm:
             unfold = paddle.nn.Unfold([3, 3], dilation=[2, 2], stride=[1, 1])
@@ -88,33 +86,95 @@ def test_error_handling(self):
             unfold = paddle.compat.nn.Unfold([3, 3], paddings=[2, 1])
         self.assertEqual(str(cm.exception), msg_gt_2)
 
-        with self.assertRaises(ValueError) as cm:
-            unfold = paddle.compat.nn.Unfold([3, 3], padding=[2, 1, 2, 2])
-            res = unfold(paddle.ones([2, 2, 5, 5]))
-        self.assertEqual(str(cm.exception), msg_gt_3)
+
+class TestCompatFunctionalUnfold(unittest.TestCase):
+    def _compare_with_origin(
+        self, input_tensor, kernel_size, dilation, padding, stride
+    ):
+        out_compat = F_compat.unfold(
+            input=input_tensor,
+            kernel_size=kernel_size,
+            dilation=dilation,
+            padding=padding,
+            stride=stride,
+        )
+
+        out_origin = paddle.nn.functional.unfold(
+            x=input_tensor,
+            kernel_sizes=kernel_size
+            if not isinstance(kernel_size, paddle.Tensor)
+            else kernel_size.tolist(),
+            dilations=dilation
+            if not isinstance(dilation, paddle.Tensor)
+            else dilation.tolist(),
+            paddings=padding
+            if not isinstance(padding, paddle.Tensor)
+            else padding.tolist(),
+            strides=stride
+            if not isinstance(stride, paddle.Tensor)
+            else stride.tolist(),
+        )
+
+        expected_res = out_origin.numpy()
+        np.testing.assert_allclose(out_compat.numpy(), expected_res)
+
+        to_tensor = lambda x: x if isinstance(x, int) else paddle.to_tensor(x)
+        k_t = (
+            to_tensor(kernel_size)
+            if not isinstance(kernel_size, paddle.Tensor)
+            else kernel_size
+        )
+        d_t = (
+            to_tensor(dilation)
+            if not isinstance(dilation, paddle.Tensor)
+            else dilation
+        )
+        p_t = (
+            to_tensor(padding)
+            if not isinstance(padding, paddle.Tensor)
+            else padding
+        )
+        s_t = (
+            to_tensor(stride)
+            if not isinstance(stride, paddle.Tensor)
+            else stride
+        )
+
+        out_compat_tensor = F_compat.unfold(
+            input=input_tensor,
+            kernel_size=k_t,
+            dilation=d_t,
+            padding=p_t,
+            stride=s_t,
+        )
+        np.testing.assert_allclose(out_compat_tensor.numpy(), expected_res)
+
+    def test_compare_with_origin(self):
+        input_shape = (3, 4, 5, 6)
+        input_tensor = paddle.arange(360, dtype=paddle.float32).reshape(
+            input_shape
+        )
+        self._compare_with_origin(input_tensor, [3, 3], [1, 1], (1, 2), [1, 1])
+
+        input_shape = (5, 10, 13, 13)
+        input_tensor = paddle.ones(input_shape, dtype=paddle.float64)
+        self._compare_with_origin(input_tensor, [4, 4], [2, 2], 1, (1, 2))
+
+        input_shape = (12, 4, 10, 10)
+        input_tensor = paddle.ones(input_shape, dtype=paddle.float64)
+        self._compare_with_origin(input_tensor, 3, 2, 1, (1, 1))
+
+    def test_error_handling(self):
+        """Test whether there will be correct exception when users pass incorrect kwargs."""
+        x = paddle.randn([3, 9, 5, 5])
+
+        msg_gt_wrong_key = "paddle.compat.nn.functional.unfold() received unexpected keyword argument 'paddings'. \nDid you mean to use paddle.nn.functional.unfold() instead?"
 
         with self.assertRaises(TypeError) as cm:
-            paddle.enable_static()
-            input_data = np.random.randn(2, 4, 8, 8).astype(np.float32)
-            with paddle.static.program_guard(paddle.static.Program()):
-                x = paddle.static.data(
-                    name='x', shape=[None, None, 8, 8], dtype='float32'
-                )
-                place = (
-                    get_device_place()
-                    if (paddle.is_compiled_with_cuda() or is_custom_device())
-                    else paddle.CPUPlace()
-                )
-                unfold_pass = paddle.compat.nn.Unfold(
-                    kernel_size=paddle.to_tensor([3, 3]),
-                    padding=paddle.to_tensor([1, 2]),
-                )
-                result = unfold_pass(x)
-                exe = paddle.static.Executor(place)
-                feed = {'x': input_data}
-                exe_res = exe.run(feed=feed)
-            paddle.disable_static()
-        self.assertEqual(str(cm.exception), msg_gt_4)
+            F_compat.unfold(x, [3, 3], paddings=[2, 1])
+        self.assertEqual(str(cm.exception), msg_gt_wrong_key)
+
+        paddle.disable_static()
 
 
 if __name__ == '__main__':
diff --git a/test/legacy_test/test_unflatten.py b/test/legacy_test/test_unflatten.py
