[API-Compat] CN docs for compat.Unfold/split/sort/min/max

docs/api/index_cn.rst

@@ -31,6 +31,9 @@ API 文档
 | paddle.callbacks         | 日志回调类，包括 ModelCheckpoint、                                                 |
 |                          | ProgBarLogger 等。                                                                 |
 +--------------------------+------------------------------------------------------------------------------------+
+| paddle.compat            | PyTorch 兼容的函数与模块，                                                         |
+|                          | 行为与 PyTorch 对应接口一致                                                        |
++--------------------------+------------------------------------------------------------------------------------+
 | paddle.device            | 设备管理相关 API，包括 set_device、get_device 等。                                 |
 +--------------------------+------------------------------------------------------------------------------------+
 | paddle.distributed       | 分布式相关基础 API。                                                               |

docs/api/index_en.rst

@@ -34,6 +34,9 @@ In this version, PaddlePaddle has made many optimizations to the APIs. You can r
 | paddle.callbacks         | Paddle log callback APIs, including ModelCheckpoint,          |
 |                          | ProgBarLogger, etc.                                           |
 +--------------------------+---------------------------------------------------------------+
+| paddle.compat            | PyTorch-compatible APIs, with identical calling methods       |
+|                          | and behaviors to their PyTorch counterparts.                  |
++--------------------------+---------------------------------------------------------------+
 | paddle.device            | Device management related APIs, such as set_device,           |
 |                          | get_device, etc.                                              |
 +--------------------------+---------------------------------------------------------------+

docs/api/paddle/compat/Overview_cn.rst

@@ -0,0 +1,32 @@
+.. _cn_overview_compat:
+
+paddle.compat
+---------------------
+
+paddle.compat 目录下包含飞桨框架支持的 PyTorch 兼容函数与模块接口
+
+.. _about_compat_funcs:
+
+PyTorch 兼容函数
+::::::::::::::::::::
+
+.. csv-table::
+    :header: "API 名称", "API 功能"
+    :widths: 10, 30
+
+    " :ref:`max <cn_api_paddle_compat_max>` ", "包含 `amax`、同时返回 values 及 indices 的轴向最大值、`maximum` 三种功能"
+    " :ref:`min <cn_api_paddle_compat_min>` ", "包含 `amin`、同时返回 values 及 indices 的轴向最小值、`minimum` 三种功能"
+    " :ref:`sort <cn_api_paddle_compat_sort>` ", "同时返回 values 及 indices 的排序"
+    " :ref:`split <cn_api_paddle_compat_split>` ", "允许非整除块大小输入的 Tensor 轴向切分"
+
+
+.. _about_compat_class:
+
+PyTorch 兼容模块
+::::::::::::::::::::
+
+.. csv-table::
+    :header: "类名称", "类功能"
+    :widths: 10, 30
+
+    " :ref:`Unfold <cn_api_paddle_compat_Unfold>` ", "允许 Tensor 输入的 ``paddle.nn.Unfold`` 兼容版本"

docs/api/paddle/compat/Unfold_cn.rst

@@ -0,0 +1,54 @@
+.. _cn_api_paddle_compat_Unfold:
+
+Unfold
+-------------------------------
+
+.. py:class:: paddle.compat.Unfold(kernel_size, dilation=1, padding=0, stride=1)
+
+
+PyTorch 兼容的 :ref:`cn_api_paddle_nn_Unfold` 版本：
+    - 关键字参数使用单数形式（例如：``kernel_size`` 而非 kernel_sizes）
+    - ``padding`` 仅支持输入长度为 1（整数）或 2 的列表，禁止使用 Size4 格式。如需更灵活的输入版本，请使用 :ref:`cn_api_paddle_nn_Unfold`
+    - 所有输入参数支持 ``Tensor`` 或 ``pir.Value`` 类型（将自动转换为列表）
+    - 其他特性与 :ref:`cn_api_paddle_nn_Unfold` 完全一致
+
+使用前请详细参考：`【仅参数名不一致】torch.nn.Unfold`_ 以确定是否使用此模块。
+
+.. _【仅参数名不一致】torch.nn.Unfold: https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/guides/model_convert/convert_from_pytorch/api_difference/nn/torch.nn.Unfold.html
+
+**样例**：
+
+::
+
+      Given:
+        x.shape = [5, 10, 25, 25]
+        kernel_size = [3, 3]
+        stride = 1
+        padding = 1
+
+      Return:
+        out.shape = [5, 90, 625]
+
+功能说明
+:::::::::::
+实现卷积中的 im2col 操作，将卷积核覆盖区域的元素重排列为列向量。输入形状为 [N, C, H, W] 的 ``x`` 将输出形状为 [N, Cout, Lout] 的张量。
+
+
+参数
+:::::::::::
+
+        - **kernel_size** (int|list|tuple|Tensor) - 卷积核尺寸。接受 ``[k_h, k_w]`` 或整数 ``k`` （视为  ``[k, k]``）
+        - **dilation** (int|list|tuple|Tensor, 可选) - 卷积膨胀系数。接受单整数或 ``[dilation_h, dilation_w]``。单整数 ``dilation`` 视为 ``[dilation, dilation]``。默认为 1
+        - **padding** (int|list|tuple|Tensor, 可选) - 各维度填充大小。接受单整数或 ``[padding_h, padding_w]``。``[padding_h, padding_w]`` 将扩展为 ``[padding_h, padding_w, padding_h, padding_w]``。单整数 ``padding`` 将转为 ``[padding, padding, padding, padding]``。默认为 0
+        - **stride** (int|list|tuple|Tensor, 可选) - 滑动步长。接受单整数或 ``[stride_h, stride_w]``。单整数 ``stride`` 视为 ``[stride, stride]``。默认为 1
+
+形状
+:::::::::
+ - **输入** : 4-D Tensor，形状为[N, C, H, W]，数据类型为 float32 或者 float64
+ - **输出**：形状如上面所描述的[N, Cout, Lout]，Cout 每一个滑动 block 里面覆盖的元素个数，Lout 是滑动 block 的个数，数据类型与 ``x`` 相同
+
+
+代码示例
+::::::::::::
+
+COPY-FROM: paddle.compat.Unfold

docs/api/paddle/compat/max_cn.rst

@@ -0,0 +1,97 @@
+.. _cn_api_paddle_compat_max:
+
+max
+-------------------------------
+
+.. note::
+
+    PyTorch 兼容的 :ref:`cn_api_paddle_max` 版本，本接口根据输入参数的不同，包含三种不同的功能。
+
+    使用前请详细参考：`【返回参数类型不一致】torch.max`_ 以确定是否使用此模块。
+
+.. _【返回参数类型不一致】torch.max: https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/guides/model_convert/convert_from_pytorch/api_difference/torch/torch.max.html
+
+
+.. caution::
+
+    下面列举的三种功能参数输入方式 **互斥**，混用非公共的参数输入方法将会导致报错，请谨慎使用。
+
+
+=====
+
+
+.. py:function:: paddle.compat.max(x, out=None)
+
+
+对整个 input tensor 求最大值，见 `paddle.amax` :ref:`cn_api_paddle_amax`
+
+.. note::
+
+    对输入有多个最大值的情况下，``paddle.compat.max`` 的梯度表现与 ``paddle.amax`` 一致：会将梯度平均传回到最大值对应的位置。``out`` 返回方法与静态图联合使用是被禁止的行为，静态图下将报错。
+
+参数
+:::::::::
+   - **x** （Tensor）- Tensor，支持数据类型为 bfloat16、float16、float32、float64、int32、int64（CUDA GPU），而 uint8, int32, int64, float32, float64 在 CPU 设备上被支持。
+   - **out** (Tensor，可选) - 用于引用式传入输出值，注意：动态图下 out 可以是任意 Tensor，默认值为 None。
+
+返回
+:::::::::
+   Tensor，最大值运算的 Tensor（0D），数据类型和输入数据类型一致。
+
+
+=====
+
+
+.. py:function:: paddle.compat.max(x, dim=None, keepdim=False, out=None)
+
+
+.. note::
+
+    对输入有多个最大值的情况下，`paddle.compat.max` 将只返回梯度值给 ``indices`` 中选择的位置。``out`` 返回方法与静态图联合使用是被禁止的行为，静态图下将报错。
+
+参数
+:::::::::
+   - **x** （Tensor）- Tensor，支持数据类型为 bfloat16、float16、float32、float64、int32、int64（CUDA GPU），而 uint8, int32, int64, float32, float64 在 CPU 设备上被支持。
+   - **dim** （list|tuple|int，可选）- 求最大值运算的维度。必须在 :math:`[−x.ndim, x.ndim]` 范围内。如果 :math:`dim[i] < 0`，则维度将变为 :math:`x.ndim+dim[i]`，默认值为 None。注意，手动传入 ``dim=None`` 是不允许的，``dim`` 不可显式被指定为 None。如果需要对整个 tensor 求解全局最大值，请使用第一种参数写法。
+   - **keepdim** (bool，可选) - 是否在输出 Tensor 中保留输入的维度。除非 keepdim 为 True，否则输出 Tensor 的维度将比输入 Tensor 小一维，默认值为 False。注意，不传入 ``dim`` 时传入本参数是不允许的！
+   - **out** (tuple(Tensor, Tensor)，可选) - 用于引用式传入输出值。``values`` 在前，``indices`` 在后。注意：动态图下 out 可以是任意 Tensor，默认值为 None。
+
+返回
+:::::::::
+MinMaxRetType(Tensor, Tensor)，此处的 ``MinMaxRetType`` 是一个具名元组，含有 ``values`` （在前）和 ``indices`` （在后）两个域，用法与 tuple 一致。
+
+
+=====
+
+
+.. py:function:: paddle.compat.max(x, other, out=None)
+
+
+与 ``other`` Tensor 计算逐元素最大值。见 `paddle.maximum` :ref:`cn_api_paddle_maximum`
+
+.. note::
+
+    ``out`` 返回方法与静态图联合使用是被禁止的行为，静态图下将报错。
+
+参数
+:::::::::
+   - **x** （Tensor）- Tensor，支持数据类型为 bfloat16、float16、float32、float64、int32、int64（CUDA GPU），而 uint8, int32, int64, float32, float64 在 CPU 设备上被支持。
+   - **other** （Tensor）- Tensor，支持类型见 ``x``。注意，``other`` 的 shape 必须可以被广播到 ``x`` 的 shape。
+   - **out** (Tensor，可选) - 用于引用式传入输出值，注意：动态图下 out 可以是任意 Tensor，默认值为 None。
+
+返回
+:::::::::
+   Tensor，逐元素最大的结果，形状、数据类型与 place 与 ``x`` 一致。
+
+
+=====
+
+
+代码示例
+::::::::::
+
+.. note::
+
+    以下示例为上述三种不同输入方法对应功能的示例。
+
+COPY-FROM: paddle.compat.max

docs/api/paddle/compat/min_cn.rst

@@ -0,0 +1,97 @@
+.. _cn_api_paddle_compat_min:
+
+min
+-------------------------------
+
+.. note::
+
+    PyTorch 兼容的 :ref:`cn_api_paddle_min` 版本，本接口根据输入参数的不同，包含三种不同的功能。
+
+    使用前请详细参考：`【返回参数类型不一致】torch.min`_ 以确定是否使用此模块。
+
+.. _【返回参数类型不一致】torch.min: https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/guides/model_convert/convert_from_pytorch/api_difference/torch/torch.min.html
+
+
+.. caution::
+
+    下面列举的三种功能参数输入方式 **互斥**，混用非公共的参数输入方法将会导致报错，请谨慎使用。
+
+
+=====
+
+
+.. py:function:: paddle.compat.min(x, out=None)
+
+
+对整个 input tensor 求最小值，见 `paddle.amin` :ref:`cn_api_paddle_amin`
+
+.. note::
+
+    对输入有多个最小值的情况下，``paddle.compat.min`` 的梯度表现与 ``paddle.amin`` 一致：会将梯度平均传回到最小值对应的位置。``out`` 返回方法与静态图联合使用是被禁止的行为，静态图下将报错。
+
+参数
+:::::::::
+   - **x** （Tensor）- Tensor，支持数据类型为 bfloat16、float16、float32、float64、int32、int64（CUDA GPU），而 uint8, int32, int64, float32, float64 在 CPU 设备上被支持。
+   - **out** (Tensor，可选) - 用于引用式传入输出值，注意：动态图下 out 可以是任意 Tensor，默认值为 None。
+
+返回
+:::::::::
+   Tensor，最小值运算的 Tensor（0D），数据类型和输入数据类型一致。
+
+
+=====
+
+
+.. py:function:: paddle.compat.min(x, dim=None, keepdim=False, out=None)
+
+
+.. note::
+
+    对输入有多个最小值的情况下，`paddle.compat.min` 将只返回梯度值给 ``indices`` 中选择的位置。``out`` 返回方法与静态图联合使用是被禁止的行为，静态图下将报错。
+
+参数
+:::::::::
+   - **x** （Tensor）- Tensor，支持数据类型为 bfloat16、float16、float32、float64、int32、int64（CUDA GPU），而 uint8, int32, int64, float32, float64 在 CPU 设备上被支持。
+   - **dim** （list|tuple|int，可选）- 求最小值运算的维度。必须在 :math:`[−x.ndim, x.ndim]` 范围内。如果 :math:`dim[i] < 0`，则维度将变为 :math:`x.ndim+dim[i]`，默认值为 None。注意，手动传入 ``dim=None`` 是不允许的，``dim`` 不可显式被指定为 None。如果需要对整个 tensor 求解全局最小值，请使用第一种参数写法。
+   - **keepdim** (bool，可选) - 是否在输出 Tensor 中保留输入的维度。除非 keepdim 为 True，否则输出 Tensor 的维度将比输入 Tensor 小一维，默认值为 False。注意，不传入 ``dim`` 时传入本参数是不允许的！
+   - **out** (tuple(Tensor, Tensor)，可选) - 用于引用式传入输出值。``values`` 在前，``indices`` 在后。注意：动态图下 out 可以是任意 Tensor，默认值为 None。
+
+返回
+:::::::::
+MinMaxRetType(Tensor, Tensor)，此处的 ``MinMaxRetType`` 是一个具名元组，含有 ``values`` （在前）和 ``indices`` （在后）两个域，用法与 tuple 一致。
+
+
+=====
+
+
+.. py:function:: paddle.compat.min(x, other, out=None)
+
+
+与 ``other`` Tensor 计算逐元素最小值。见 `paddle.minimum` :ref:`cn_api_paddle_minimum`
+
+.. note::
+
+    ``out`` 返回方法与静态图联合使用是被禁止的行为，静态图下将报错。
+
+参数
+:::::::::
+   - **x** （Tensor）- Tensor，支持数据类型为 bfloat16、float16、float32、float64、int32、int64（CUDA GPU），而 uint8, int32, int64, float32, float64 在 CPU 设备上被支持。
+   - **other** （Tensor）- Tensor，支持类型见 ``x``。注意，``other`` 的 shape 必须可以被广播到 ``x`` 的 shape。
+   - **out** (Tensor，可选) - 用于引用式传入输出值，注意：动态图下 out 可以是任意 Tensor，默认值为 None。
+
+返回
+:::::::::
+   Tensor，逐元素最小的结果，形状、数据类型与 place 与 ``x`` 一致。
+
+
+=====
+
+
+代码示例
+::::::::::
+
+.. note::
+
+    以下示例为上述三种不同输入方法对应功能的示例。
+
+COPY-FROM: paddle.compat.min

docs/api/paddle/compat/sort_cn.rst

@@ -0,0 +1,32 @@
+.. _cn_api_paddle_compat_sort:
+
+sort
+-------------------------------
+
+.. py:function:: paddle.compat.sort(input, dim=-1, descending=False, stable=False, out=None)
+
+PyTorch 兼容的 :ref:`cn_api_paddle_sort` 版本，同时返回排序的值结果以及索引值。对输入变量沿给定轴进行排序，输出排序好的数据，其维度和输入相同。默认升序排列，如果需要降序排列设置 ``descending=True`` 。
+
+使用前请详细参考：`【返回参数类型不一致】torch.sort`_ 以确定是否使用此模块。
+
+.. _【返回参数类型不一致】torch.sort: https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/guides/model_convert/convert_from_pytorch/api_difference/torch/torch.sort.html
+
+
+参数
+::::::::::::
+
+    - **input** (Tensor) - 输入的多维 ``Tensor``，支持的数据类型：float32, float64, int16, int32, int64, uint8, float16, bfloat16。
+    - **dim** (int，可选) - 指定对输入 Tensor 进行运算的轴，``dim`` 的有效范围是[-R, R)，R 是输入 ``x`` 的 Rank， ``dim`` 为负时与 ``dim`` +R 等价。默认值为-1。
+    - **descending** (bool，可选) - 指定算法排序的方向。如果设置为 True，算法按照降序排序。如果设置为 False 或者不设置，按照升序排序。默认值为 False。
+    - **stable** (bool，可选) - 是否使用稳定排序算法。若设置为 True，则使用稳定排序算法，即相同元素的顺序在排序结果中将会被保留。默认值为 False，此时的算法不一定是稳定排序算法。
+    - **out** (tuple(Tensor, Tensor)，可选) - 用于引用式传入输出值。``values`` 在前，``indices`` 在后。注意：动态图下 out 可以是任意 Tensor，默认值为 None。``out`` 返回方法与静态图联合使用是被禁止的行为，静态图下将报错。
+
+返回
+::::::::::::
+SortRetType(Tensor, Tensor)，此处的 ``SortRetType`` 是一个具名元组，含有 ``values`` （在前）和 ``indices`` （在后）两个域，用法与 tuple 一致。
+
+
+代码示例
+::::::::::::
+
+COPY-FROM: paddle.compat.sort

docs/api/paddle/compat/split_cn.rst

@@ -0,0 +1,33 @@
+.. _cn_api_paddle_compat_split:
+
+split
+-------------------------------
+
+.. py:function:: paddle.compat.split(tensor, split_size_or_sections, dim=0)
+
+
+PyTorch 兼容的 :ref:`cn_api_paddle_split` 版本，允许了非整除的 ``split_size_or_sections`` 输入
+
+使用前请详细参考：`【输入参数用法不一致】torch.split`_ 以确定是否使用此模块。
+
+.. _【输入参数用法不一致】torch.split: https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/guides/model_convert/convert_from_pytorch/api_difference/torch/torch.split.html
+
+.. note::
+    此 API 遵循 ``torch.split`` 的函数签名和行为以实现 PyTorch 兼容。
+    如需使用 Paddle 原生实现，请参考 :ref:`cn_api_paddle_split`
+
+参数
+:::::::::
+       - **tensor** (Tensor) - 输入 N 维 Tensor，支持 bool、bfloat16、float16、float32、float64、uint8、int8、int32 或 int64 数据类型
+       - **split_size_or_sections** (int|list|tuple) - 若为整数，则将 Tensor 均匀分割为指定大小的块，与 :ref:`cn_api_paddle_split` 不同，本 API 不要求此参数整除对应维度的通道数：非整除情况下输出元组的最后一个 tensor 对应维度将为余数大小，小于此值。若为列表/元组，则按指定尺寸分割，禁止使用负值（例如对 9 通道的维度，``[2,3,-1]`` 会被拒绝）
+       - **dim** (int|Tensor, 可选) - 分割维度，可为整数或形状为[]的 0-D Tensor（数据类型需为 ``int32`` 或 ``int64``）。若 ``dim < 0``，则实际维度为 ``rank(x) + dim``。默认值：0
+
+返回
+:::::::::
+tuple(Tensor)，分割后的 Tensor 元组
+
+
+代码示例
+:::::::::
+
+COPY-FROM: paddle.compat.split