【Hackathon 5th No.33】为 Paddle 新增 atleast_1d / atleast_2d / atleast_3d API (#6317)

megemini · web-flow · commit 55d19d687270 · 2023-11-29T17:51:16.000+08:00
* [Add] atleast_Nd cn doc

* [Update] return of list

* [Add] torch paddle mapping

* [Update] desc

* [Change] params desc

* [Change] atleast_xd with same shape tuple inputs

* [Change] atleast for tuple input

* [Update] convert pytorch

* [Change] torch.atleast_xd.md
diff --git a/docs/api/paddle/Overview_cn.rst b/docs/api/paddle/Overview_cn.rst
@@ -358,6 +358,9 @@ tensor 元素操作相关（如：转置，reshape 等）
     " :ref:`paddle.gather <cn_api_paddle_gather>` ", "根据索引 index 获取输入 x 的指定 aixs 维度的条目，并将它们拼接在一起"
     " :ref:`paddle.gather_nd <cn_api_paddle_gather_nd>` ", "paddle.gather 的高维推广"
     " :ref:`paddle.reshape <cn_api_paddle_reshape>` ", "在保持输入 x 数据不变的情况下，改变 x 的形状"
+    " :ref:`paddle.atleast_1d <cn_api_paddle_atleast_1d>` ", "将输入转换为张量并返回至少为 ``1`` 维的视图"
+    " :ref:`paddle.atleast_2d <cn_api_paddle_atleast_2d>` ", "将输入转换为张量并返回至少为 ``2`` 维的视图"
+    " :ref:`paddle.atleast_3d <cn_api_paddle_atleast_3d>` ", "将输入转换为张量并返回至少为 ``3`` 维的视图"
     " :ref:`paddle.roll <cn_api_paddle_roll>` ", "沿着指定维度 axis 对输入 x 进行循环滚动，当元素移动到最后位置时，会从第一个位置重新插入"
     " :ref:`paddle.scatter <cn_api_paddle_distributed_scatter>` ", "通过基于 updates 来更新选定索引 index 上的输入来获得输出"
     " :ref:`paddle.scatter_nd <cn_api_paddle_scatter_nd>` ", "根据 index ，将 updates 添加到一个新的张量中，从而得到输出的 Tensor"
diff --git a/docs/api/paddle/Tensor_cn.rst b/docs/api/paddle/Tensor_cn.rst
@@ -3082,6 +3082,29 @@ masked_fill_(x, mask, value, name=None)
 
 Inplace 版本的 :ref:`cn_api_paddle_masked_fill` API，对输入 `x` 采用 Inplace 策略。
 
+atleast_1d(name=None)
+:::::::::
+将输入转换为张量并返回至少为 ``1`` 维的视图。 ``1`` 维或更高维的输入会被保留。
+
+返回至少为 ``1`` 维视图的 Tensor 。
+
+请参考 :ref:`cn_api_paddle_atleast_1d`
+
+atleast_2d(name=None)
+:::::::::
+将输入转换为张量并返回至少为 ``2`` 维的视图。 ``2`` 维或更高维的输入会被保留。
+
+返回至少为 ``2`` 维视图的 Tensor 。
+
+请参考 :ref:`cn_api_paddle_atleast_2d`
+
+atleast_3d(name=None)
+:::::::::
+将输入转换为张量并返回至少为 ``3`` 维的视图。 ``3`` 维或更高维的输入会被保留。
+
+返回至少为 ``3`` 维视图的 Tensor 。
+
+请参考 :ref:`cn_api_paddle_atleast_3d`
 diagonal_scatter(x, y, offset=0, axis1=0, axis2=1, name=None)
 :::::::::
 根据给定的轴 axis 和偏移量 offset，将张量 y 的值填充到张量 x 中。
diff --git a/docs/api/paddle/atleast_1d_cn.rst b/docs/api/paddle/atleast_1d_cn.rst
@@ -0,0 +1,23 @@
+.. _cn_api_paddle_atleast_1d:
+
+atleast_1d
+-------------------------------
+
+.. py:function:: paddle.atleast_1d(*inputs, name=None)
+
+将输入转换为张量并返回至少为 ``1`` 维的视图。标量输入会被转换， ``1`` 维或更高维的输入则会被保留。
+
+参数
+::::::::::::
+
+    - **inputs** (Tensor|list(Tensor)) - 一个或多个 Tensor，数据类型为： ``float16``, ``float32``, ``float64``, ``int16``, ``int32``, ``int64``, ``int8``, ``uint8``, ``complex64``, ``complex128``, ``bfloat16`` 或 ``bool``。
+    - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。
+
+返回
+::::::::::::
+Tensor 或者由 Tensor 组成的 list。当只有一个输入的时候返回一个 Tensor，当有多个输入的时候返回由 Tensor 组成的 list。
+
+代码示例
+::::::::::::
+
+COPY-FROM: paddle.atleast_1d
diff --git a/docs/api/paddle/atleast_2d_cn.rst b/docs/api/paddle/atleast_2d_cn.rst
@@ -0,0 +1,23 @@
+.. _cn_api_paddle_atleast_2d:
+
+atleast_2d
+-------------------------------
+
+.. py:function:: paddle.atleast_2d(*inputs, name=None)
+
+将输入转换为张量并返回至少为 ``2`` 维的视图。 ``2`` 维或更高维的输入会被保留。
+
+参数
+::::::::::::
+
+    - **inputs** (Tensor|list(Tensor)) - 一个或多个 Tensor，数据类型为： ``float16``, ``float32``, ``float64``, ``int16``, ``int32``, ``int64``, ``int8``, ``uint8``, ``complex64``, ``complex128``, ``bfloat16`` 或 ``bool``。
+    - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。
+
+返回
+::::::::::::
+Tensor 或者由 Tensor 组成的 list。当只有一个输入的时候返回一个 Tensor，当有多个输入的时候返回由 Tensor 组成的 list。
+
+代码示例
+::::::::::::
+
+COPY-FROM: paddle.atleast_2d
diff --git a/docs/api/paddle/atleast_3d_cn.rst b/docs/api/paddle/atleast_3d_cn.rst
@@ -0,0 +1,23 @@
+.. _cn_api_paddle_atleast_3d:
+
+atleast_3d
+-------------------------------
+
+.. py:function:: paddle.atleast_3d(*inputs, name=None)
+
+将输入转换为张量并返回至少为 ``3`` 维的视图。 ``3`` 维或更高维的输入会被保留。
+
+参数
+::::::::::::
+
+    - **inputs** (Tensor|list(Tensor)) - 一个或多个 Tensor，数据类型为： ``float16``, ``float32``, ``float64``, ``int16``, ``int32``, ``int64``, ``int8``, ``uint8``, ``complex64``, ``complex128``, ``bfloat16`` 或 ``bool``。
+    - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。
+
+返回
+::::::::::::
+Tensor 或者由 Tensor 组成的 list。当只有一个输入的时候返回一个 Tensor，当有多个输入的时候返回由 Tensor 组成的 list。
+
+代码示例
+::::::::::::
+
+COPY-FROM: paddle.atleast_3d
diff --git a/docs/guides/model_convert/convert_from_pytorch/api_difference/ops/torch.atleast_1d.md b/docs/guides/model_convert/convert_from_pytorch/api_difference/ops/torch.atleast_1d.md
@@ -0,0 +1,34 @@
+## [ 参数不一致 ]torch.atleast_1d
+
+### [torch.atleast_1d](https://pytorch.org/docs/stable/generated/torch.atleast_1d.html#torch-atleast-1d)
+
+```python
+torch.atleast_1d(*tensors)
+```
+
+### [paddle.atleast_1d](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/api/paddle/atleast_1d_cn.html#atleast_1d)
+
+```python
+paddle.atleast_1d(*inputs, name=None)
+```
+
+PyTorch 与 Paddle 参数不一致，具体如下：
+
+### 参数映射
+| PyTorch       | PaddlePaddle | 备注                                                   |
+| ------------- | ------------ | ------------------------------------------------------ |
+| <font color='red'> tensors </font> | <font color='red'> inputs </font> | 输入的 Tensor，仅当 torch 输入为 tuple(Tensor)时，两者处理方式不一致，需要转写。其他情形下均一致。 |
+
+PyTorch 与 Paddle 功能一致，但对于由多个 Tensor 组成 tuple|list 输入的处理方式略有不同，具体请看转写示例。
+
+### 转写示例
+
+#### tensors: 输入为 tuple(Tensor)时
+
+```python
+# Pytorch 写法
+torch.atleast_1d((x, y))
+
+# Paddle 写法
+paddle.atleast_1d(x, y)
+```
diff --git a/docs/guides/model_convert/convert_from_pytorch/api_difference/ops/torch.atleast_2d.md b/docs/guides/model_convert/convert_from_pytorch/api_difference/ops/torch.atleast_2d.md
@@ -0,0 +1,34 @@
+## [ 参数不一致 ]torch.atleast_2d
+
+### [torch.atleast_2d](https://pytorch.org/docs/stable/generated/torch.atleast_2d.html#torch-atleast-2d)
+
+```python
+torch.atleast_2d(*tensors)
+```
+
+### [paddle.atleast_2d](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/api/paddle/atleast_2d_cn.html#atleast_2d)
+
+```python
+paddle.atleast_2d(*inputs, name=None)
+```
+
+PyTorch 与 Paddle 参数不一致，具体如下：
+
+### 参数映射
+| PyTorch       | PaddlePaddle | 备注                                                   |
+| ------------- | ------------ | ------------------------------------------------------ |
+| <font color='red'> tensors </font> | <font color='red'> inputs </font> | 输入的 Tensor，仅当 torch 输入为 tuple(Tensor)时，两者处理方式不一致，需要转写。其他情形下均一致。 |
+
+PyTorch 与 Paddle 功能一致，但对于由多个 Tensor 组成 tuple|list 输入的处理方式略有不同，具体请看转写示例。
+
+### 转写示例
+
+#### tensors: 输入为 tuple(Tensor)时
+
+```python
+# Pytorch 写法
+torch.atleast_2d((x, y))
+
+# Paddle 写法
+paddle.atleast_2d(x, y)
+```
diff --git a/docs/guides/model_convert/convert_from_pytorch/api_difference/ops/torch.atleast_3d.md b/docs/guides/model_convert/convert_from_pytorch/api_difference/ops/torch.atleast_3d.md
@@ -0,0 +1,34 @@
+## [ 参数不一致 ]torch.atleast_3d
+
+### [torch.atleast_3d](https://pytorch.org/docs/stable/generated/torch.atleast_3d.html#torch-atleast-3d)
+
+```python
+torch.atleast_3d(*tensors)
+```
+
+### [paddle.atleast_3d](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/api/paddle/atleast_3d_cn.html#atleast_3d)
+
+```python
+paddle.atleast_3d(*inputs, name=None)
+```
+
+PyTorch 与 Paddle 参数不一致，具体如下：
+
+### 参数映射
+| PyTorch       | PaddlePaddle | 备注                                                   |
+| ------------- | ------------ | ------------------------------------------------------ |
+| <font color='red'> tensors </font> | <font color='red'> inputs </font> | 输入的 Tensor，仅当 torch 输入为 tuple(Tensor)时，两者处理方式不一致，需要转写。其他情形下均一致。 |
+
+PyTorch 与 Paddle 功能一致，但对于由多个 Tensor 组成 tuple|list 输入的处理方式略有不同，具体请看转写示例。
+
+### 转写示例
+
+#### tensors: 输入为 tuple(Tensor)时
+
+```python
+# Pytorch 写法
+torch.atleast_3d((x, y))
+
+# Paddle 写法
+paddle.atleast_3d(x, y)
+```
diff --git a/docs/guides/model_convert/convert_from_pytorch/pytorch_api_mapping_cn.md b/docs/guides/model_convert/convert_from_pytorch/pytorch_api_mapping_cn.md
@@ -368,6 +368,9 @@
 | REFERENCE-MAPPING-ITEM(`torch.is_grad_enabled`, https://github.com/PaddlePaddle/docs/tree/develop/docs/guides/model_convert/convert_from_pytorch/api_difference/others/torch.is_grad_enabled.md) |
 | REFERENCE-MAPPING-ITEM(`torch.manual_seed`, https://github.com/PaddlePaddle/docs/tree/develop/docs/guides/model_convert/convert_from_pytorch/api_difference/others/torch.manual_seed.md) |
 | [torch.can_cast](https://pytorch.org/docs/stable/generated/torch.can_cast.html#torch-can-cast)                                                                    | 功能缺失 |
+| REFERENCE-MAPPING-ITEM(`torch.atleast_1d`, https://github.com/PaddlePaddle/docs/tree/develop/docs/guides/model_convert/convert_from_pytorch/api_difference/ops/torch.atleast_1d.md) |
+| REFERENCE-MAPPING-ITEM(`torch.atleast_2d`, https://github.com/PaddlePaddle/docs/tree/develop/docs/guides/model_convert/convert_from_pytorch/api_difference/ops/torch.atleast_2d.md) |
+| REFERENCE-MAPPING-ITEM(`torch.atleast_3d`, https://github.com/PaddlePaddle/docs/tree/develop/docs/guides/model_convert/convert_from_pytorch/api_difference/ops/torch.atleast_3d.md) |
 
 
 ***持续更新...***
@@ -1234,6 +1237,7 @@
 | NOT-IMPLEMENTED-ITEM(`torch.Tensor.dequantize`, https://pytorch.org/docs/1.13/generated/torch.Tensor.dequantize.html?highlight=torch+tensor+dequantize#torch.Tensor.dequantize) |
 | NOT-IMPLEMENTED-ITEM(`torch.Tensor.sum_to_size`, https://pytorch.org/docs/stable/generated/torch.Tensor.sum_to_size.html?highlight=sum_to_size#torch.Tensor.sum_to_size) |
 | NOT-IMPLEMENTED-ITEM(`torch.Tensor.resize_`, https://pytorch.org/docs/stable/generated/torch.Tensor.resize_.html?highlight=resize#torch.Tensor.resize_) |
+
 ***持续更新...***
 
 ## torch.nn.init.XX API 映射列表
