[API-Compat] Add paddle.compat.Unfold that supports tensor inputs.

Author: Enigmatisms

python/paddle/__init__.py

@@ -122,6 +122,7 @@
     _pir_ops as _pir_ops,
     _typing as _typing,
     callbacks as callbacks,
+    compat as compat,
     fft as fft,
     hub as hub,
     linalg as linalg,

python/paddle/compat.py

@@ -0,0 +1,19 @@
+# Copyright (c) 2021 PaddlePaddle Authors. All Rights Reserved
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from .tensor.compat import (
+    Unfold,
+)
+
+__all__ = ['Unfold']

python/paddle/nn/layer/common.py

@@ -45,6 +45,8 @@
 
     _T_Padding = TypeVar("_T_Padding", Tensor, Sequence[int])
 
+from paddle.utils.decorator_utils import ForbidKeywordsDecorator
+
 __all__ = []
 
 
@@ -1908,6 +1910,11 @@ class Unfold(Layer):
     strides: Size2
     name: str | None
 
+    @ForbidKeywordsDecorator(
+        illegal_keys={"kernel_size", "dilation", "padding", "stride"},
+        func_name="paddle.nn.Unfold",
+        correct_name="paddle.compat.Unfold",
+    )
     def __init__(
         self,
         kernel_sizes: Size2,

python/paddle/tensor/compat.py

@@ -0,0 +1,116 @@
+#   Copyright (c) 2022 PaddlePaddle Authors. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import paddle
+from paddle import nn
+
+if TYPE_CHECKING:
+
+    from paddle import Tensor
+    from paddle._typing import (
+        Size2,
+    )
+
+from paddle.framework import in_dynamic_mode
+from paddle.utils.decorator_utils import ForbidKeywordsDecorator
+
+__all__ = []
+
+
+class Unfold(nn.Unfold):
+    """
+    A compatible version of paddle.nn.Unfold:
+    - The keyword arguments are in non-plural forms, example: `kernel_size` instead of kernel_sizes
+    - `padding` restricts the size of the input to be 1(int) or 2, Size4 is not allowed. To use a more
+       input-flexible version of Unfold, please refer to `paddle.nn.Unfold`.
+    - All the input parameters allow `Tensor` or `pir.Value` as inputs, and will be converted to list
+
+    Other aspects are the same. See ``paddle.nn.Unfold`` for more details.
+
+    Parameters:
+        kernel_size(int|list|tuple|Tensor): The size of convolution kernel, should be [k_h, k_w]
+            or an integer k treated as [k, k].
+        stride(int|list|tuple|Tensor, optional): The strides, should be [stride_h, stride_w]
+            or an integer stride treated as [sride, stride]. For default, strides will be [1, 1].
+        padding(int|list|tuple|Tensor, 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.
+        dilation(int|list|tuple|Tensor, optional): The dilations of convolution kernel, should be
+            [dilation_h, dilation_w], or an integer dilation treated as [dilation, dilation].
+            For default, it will be [1, 1].
+
+    Examples:
+        .. code-block:: python
+
+            >>> import paddle
+
+            >>> x = paddle.randn((100, 3, 224, 224))
+            >>> unfold = paddle.compat.Unfold(kernel_size=[3, 3])
+            >>> result = unfold(x)
+            >>> print(result.shape)
+            [100, 27, 49284]
+
+    """
+
+    kernel_sizes: Size2
+    dilations: Size2
+    paddings: Size2
+    strides: Size2
+
+    @ForbidKeywordsDecorator(
+        illegal_keys={"kernel_sizes", "dilations", "paddings", "strides"},
+        func_name="paddle.compat.Unfold",
+        correct_name="paddle.nn.Unfold",
+    )
+    def __init__(
+        self,
+        kernel_size: Size2,
+        dilation: Size2 = 1,
+        padding: Size2 = 0,
+        stride: Size2 = 1,
+    ) -> None:
+
+        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.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.Unfold can only have size 1 or 2, now len={len(res)}. \nDid you mean to use paddle.nn.Unfold() instead?"
+                )
+            return res
+
+        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),
+            dilations=to_list_if_necessary(self.dilations),
+            name=self.name,
+        )

python/paddle/utils/decorator_utils.py

@@ -131,3 +131,30 @@ def process(
             args = ()
 
         return args, kwargs
+
+
+class ForbidKeywordsDecorator(DecoratorBase):
+    """A decorator that hints users to use the correct `compat` functions, when erroneous keyword arguments are detected"""
+
+    def __init__(
+        self, illegal_keys: set[str], func_name: str, correct_name: str
+    ) -> None:
+        super().__init__()
+        self.illegal_keys = illegal_keys
+        self.func_name = func_name
+        self.correct_name = correct_name
+
+    def process(
+        self, args: tuple[Any, ...], kwargs: dict[str, Any]
+    ) -> tuple[tuple[Any, ...], dict[str, Any]]:
+        found_keys = [key for key in self.illegal_keys if key in kwargs]
+
+        if found_keys:
+            keys_str = ", ".join(f"'{key}'" for key in found_keys)
+            plural = "s" if len(found_keys) > 1 else ""
+
+            raise TypeError(
+                f"{self.func_name}() received unexpected keyword argument{plural} {keys_str}. "
+                f"\nDid you mean to use {self.correct_name}() instead?"
+            )
+        return args, kwargs

test/legacy_test/test_compat_unfold.py

@@ -0,0 +1,121 @@
+#   Copyright (c) 2019 PaddlePaddle Authors. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import unittest
+
+import numpy as np
+
+import paddle
+
+
+class TestCompatUnfold(unittest.TestCase):
+    def _compare_with_origin(
+        self, input_tensor, kernel_size, dilation, padding, stride
+    ):
+        unfold_compat = paddle.compat.Unfold(
+            kernel_size=kernel_size,
+            dilation=dilation,
+            padding=padding,
+            stride=stride,
+        )
+        unfold_origin = paddle.nn.Unfold(
+            kernel_sizes=kernel_size,
+            dilations=dilation,
+            paddings=padding,
+            strides=stride,
+        )
+        expected_res = unfold_origin(input_tensor).numpy()
+        np.testing.assert_allclose(
+            unfold_compat(input_tensor).numpy(), expected_res
+        )
+
+        # test with tensor input
+        to_tensor = lambda x: x if isinstance(x, int) else paddle.to_tensor(x)
+        kernel_size = to_tensor(kernel_size)
+        dilation = to_tensor(dilation)
+        padding = to_tensor(padding)
+        stride = to_tensor(stride)
+        unfold_compat = paddle.compat.Unfold(
+            kernel_size=kernel_size,
+            dilation=dilation,
+            padding=padding,
+            stride=stride,
+        )
+        np.testing.assert_allclose(
+            unfold_compat(input_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 paddle.split kwargs in paddle.compat.split, vice versa."""
+        x = paddle.randn([3, 9, 5])
+
+        msg_gt_1 = "paddle.nn.Unfold() received unexpected keyword arguments 'dilation', 'stride'. \nDid you mean to use paddle.compat.Unfold() instead?"
+        msg_gt_2 = "paddle.compat.Unfold() received unexpected keyword argument 'paddings'. \nDid you mean to use paddle.nn.Unfold() instead?"
+        msg_gt_3 = "The `padding` field of paddle.compat.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.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])
+        self.assertEqual(str(cm.exception), msg_gt_1)
+
+        with self.assertRaises(TypeError) as cm:
+            unfold = paddle.compat.Unfold([3, 3], paddings=[2, 1])
+        self.assertEqual(str(cm.exception), msg_gt_2)
+
+        with self.assertRaises(ValueError) as cm:
+            unfold = paddle.compat.Unfold([3, 3], padding=[2, 1, 2, 2])
+            res = unfold(paddle.ones([2, 2, 5, 5]))
+        self.assertEqual(str(cm.exception), msg_gt_3)
+
+        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 = (
+                    paddle.CUDAPlace(0)
+                    if paddle.is_compiled_with_cuda()
+                    else paddle.CPUPlace()
+                )
+                unfold_pass = paddle.compat.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)
+
+
+if __name__ == '__main__':
+    unittest.main()