diff --git a/docs/api/index_cn.rst b/docs/api/index_cn.rst index 3a14ff08827..ba85faaed2c 100644 --- a/docs/api/index_cn.rst +++ b/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。 | diff --git a/docs/api/index_en.rst b/docs/api/index_en.rst index d50009b5bd8..2b912b42187 100644 --- a/docs/api/index_en.rst +++ b/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. | +--------------------------+---------------------------------------------------------------+ diff --git a/docs/api/paddle/compat/Overview_cn.rst b/docs/api/paddle/compat/Overview_cn.rst new file mode 100644 index 00000000000..8a17b36737a --- /dev/null +++ b/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 ` ", "包含 `amax`、同时返回 values 及 indices 的轴向最大值、`maximum` 三种功能" + " :ref:`min ` ", "包含 `amin`、同时返回 values 及 indices 的轴向最小值、`minimum` 三种功能" + " :ref:`sort ` ", "同时返回 values 及 indices 的排序" + " :ref:`split ` ", "允许非整除块大小输入的 Tensor 轴向切分" + + +.. _about_compat_class: + +PyTorch 兼容模块 +:::::::::::::::::::: + +.. csv-table:: + :header: "类名称", "类功能" + :widths: 10, 30 + + " :ref:`Unfold ` ", "允许 Tensor 输入的 ``paddle.nn.Unfold`` 兼容版本" diff --git a/docs/api/paddle/compat/Unfold_cn.rst b/docs/api/paddle/compat/Unfold_cn.rst new file mode 100644 index 00000000000..5b302db0b3f --- /dev/null +++ b/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 diff --git a/docs/api/paddle/compat/max_cn.rst b/docs/api/paddle/compat/max_cn.rst new file mode 100644 index 00000000000..e7d802637bc --- /dev/null +++ b/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 diff --git a/docs/api/paddle/compat/min_cn.rst b/docs/api/paddle/compat/min_cn.rst new file mode 100644 index 00000000000..e2a58812fee --- /dev/null +++ b/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 diff --git a/docs/api/paddle/compat/sort_cn.rst b/docs/api/paddle/compat/sort_cn.rst new file mode 100644 index 00000000000..95aa599e551 --- /dev/null +++ b/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 diff --git a/docs/api/paddle/compat/split_cn.rst b/docs/api/paddle/compat/split_cn.rst new file mode 100644 index 00000000000..89901fe5166 --- /dev/null +++ b/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