Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 11 commits into from
Nov 29, 2023

Conversation

megemini
Copy link
Contributor

PR types

Others

PR changes

Docs

Description

增加 paddle.atleast_Nd 相应的中文文档。

涉及文件:

  • docs/api/paddle/Overview_cn.rst 不知道是不是要加在这里?
  • docs/api/paddle/atleast_1d_cn.rst atleast_1d
  • docs/api/paddle/atleast_2d_cn.rst atleast_2d
  • docs/api/paddle/atleast_3d_cn.rst atleast_3d

请帮忙看看是否有错误和遗漏 ~

关联 PR:PaddlePaddle/Paddle#58323

请评审 ~

Copy link

paddle-bot bot commented Nov 17, 2023

感谢你贡献飞桨文档,文档预览构建中,Docs-New 跑完后即可预览,预览链接:http://preview-pr-6317.paddle-docs-preview.paddlepaddle.org.cn/documentation/docs/zh/api/index_cn.html
预览工具的更多说明,请参考:飞桨文档预览工具

@luotao1 luotao1 added the PaddlePaddle Hackathon 飞桨黑客松活动issue与PR label Nov 17, 2023
Copy link
Collaborator

@ooooo-create ooooo-create left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

我看了看发现有个 Pytorch 2.1.0 与 Paddle develop API 映射表docs/guides/model_convert/convert_from_pytorch/pytorch_api_mapping_cn.md,这些函数 pytorch里也有,在里面添加上会更好叭~,然后添加差异分析~

这些函数可以 tensor.* 使用嘛,比如 x. atleast_1d() ,要是可以的话也需要在 docs/docs/api/paddle/Tensor_cn.rst 里添加上~,映射表里也是~~

@@ -356,6 +356,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`` 维的视图"
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

是小写的 ``

@@ -356,6 +356,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`` 维的视图"
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

同上

@@ -356,6 +356,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`` 维的视图"
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

同上


.. py:function:: paddle.atleast_1d(*inputs, name=None)

将输入转换为张量并返回至少为 ‵‵1`` 维的视图。标量输入会被转换,``1`` 维或更高维的输入则会被保留。
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

同上


.. py:function:: paddle.atleast_2d(*inputs, name=None)

将输入转换为张量并返回至少为 ‵‵2`` 维的视图。``2`` 维或更高维的输入会被保留。
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

同上


.. py:function:: paddle.atleast_3d(*inputs, name=None)

将输入转换为张量并返回至少为 ‵‵3`` 维的视图。``3`` 维或更高维的输入会被保留。
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

同上

返回
::::::::::::
一个 Tensor,当只有一个输入的时候。
多个 Tensor 组成的 list,当有多个输入的时候。
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

这样写是为了分两行展示嘛,那要加上空行~
或者感觉可以写成下面这样

Tensor 或者由 Tensor 组成的 list,当只有一个输入的时候,返回一个 .......

返回
::::::::::::
一个 Tensor,当只有一个输入的时候。
多个 Tensor 组成的 list,当有多个输入的时候。
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

同上

返回
::::::::::::
一个 Tensor,当只有一个输入的时候。
多个 Tensor 组成的 list,当有多个输入的时候。
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

同上

@megemini
Copy link
Contributor Author

Update 20231117

@ooooo-create

  • 更新 Pytorch 2.1.0 与 Paddle develop API 映射表,只是,这个文件有点乱,不知道改的对不对 😅 另外,pytorch 不支持 Tensor.atleast_xd 的方式,文档里面单列了 paddle 的
  • 修改标点符号与描述

请评审 ~

Copy link
Collaborator

@ooooo-create ooooo-create left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

89822D38AB234E4A2EC1836C3E79B89E
其余 LGTM~

| ------------- | ------------ | ------------------------------------------------------ |
| <font color='red'> tensors </font> | <font color='red'> inputs </font> | 输入的 Tensor ,仅参数名不一致。 |

PyTorch 与 Paddle 功能一致,但,对于多个 Tensor 输入的处理方式略有不同,具体请看转写示例。
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
PyTorch 与 Paddle 功能一致,但,对于多个 Tensor 输入的处理方式略有不同,具体请看转写示例。
PyTorch 与 Paddle 功能一致,但对于多个 Tensor 输入的处理方式略有不同,具体请看转写示例。

| ------------- | ------------ | ------------------------------------------------------ |
| <font color='red'> tensors </font> | <font color='red'> inputs </font> | 输入的 Tensor ,仅参数名不一致。 |

PyTorch 与 Paddle 功能一致,但,对于多个 Tensor 输入的处理方式略有不同,具体请看转写示例。
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
PyTorch 与 Paddle 功能一致,但,对于多个 Tensor 输入的处理方式略有不同,具体请看转写示例。
PyTorch 与 Paddle 功能一致,但对于多个 Tensor 输入的处理方式略有不同,具体请看转写示例。

| ------------- | ------------ | ------------------------------------------------------ |
| <font color='red'> tensors </font> | <font color='red'> inputs </font> | 输入的 Tensor ,仅参数名不一致。 |

PyTorch 与 Paddle 功能一致,但,对于多个 Tensor 输入的处理方式略有不同,具体请看转写示例。
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
PyTorch 与 Paddle 功能一致,但,对于多个 Tensor 输入的处理方式略有不同,具体请看转写示例。
PyTorch 与 Paddle 功能一致,但对于多个 Tensor 输入的处理方式略有不同,具体请看转写示例。

@@ -926,6 +929,9 @@
| 303 | [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) | | 功能缺失 |
| 304 | [torch.Tensor.resize_](https://pytorch.org/docs/stable/generated/torch.Tensor.resize_.html?highlight=resize#torch.Tensor.resize_) | | 功能缺失 |
| 305 | [torch.Tensor.masked_fill_](https://pytorch.org/docs/stable/generated/torch.Tensor.masked_fill_.html?highlight=resize#torch.Tensor.masked_fill_) | [paddle.Tensor.masked_fill_](https://www.paddlepaddle.org.cn/documentation/docs/zh/api/paddle/Tensor_cn.html#id25) | 功能完全一致 |
| 306 | | [paddle.Tensor.atleast_1d](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/api/paddle/atleast_1d_cn.html#atleast_1d) | PyTorch 功能缺失 |
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

中间多了一个 | ,渲染出来没问题,看着有点奇怪~

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

撤回,刚刚没看清,sorry

@@ -0,0 +1,44 @@
## [ 参数不一致 ]torch.atleast_3d
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

这个算 仅参数不一致 嘛,还是 参数不一致,不确定捏,孙师傅快来 @sunzhongkai588
是因为 两者对 (x,y) 的处理不一致
image

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

嗯 很纠结 不知道该咋写 😂 ~~~

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

这个算 仅参数不一致 嘛,还是 参数不一致,不确定捏,孙师傅快来 @sunzhongkai588
是因为 两者对 (x,y) 的处理不一致

@zhwesky2010 麻烦看一下, atleast_1d / atleast_2d / atleast_3d 和 torch 属于那种不一致

@@ -926,6 +929,9 @@
| 303 | [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) | | 功能缺失 |
| 304 | [torch.Tensor.resize_](https://pytorch.org/docs/stable/generated/torch.Tensor.resize_.html?highlight=resize#torch.Tensor.resize_) | | 功能缺失 |
| 305 | [torch.Tensor.masked_fill_](https://pytorch.org/docs/stable/generated/torch.Tensor.masked_fill_.html?highlight=resize#torch.Tensor.masked_fill_) | [paddle.Tensor.masked_fill_](https://www.paddlepaddle.org.cn/documentation/docs/zh/api/paddle/Tensor_cn.html#id25) | 功能完全一致 |
| 306 | | [paddle.Tensor.atleast_1d](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/api/paddle/atleast_1d_cn.html#atleast_1d) | PyTorch 功能缺失 |
| 307 | | [paddle.Tensor.atleast_2d](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/api/paddle/atleast_2d_cn.html#atleast_2d) | PyTorch 功能缺失 |
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

这个如果pytorch没有,paddle的也不用写,只用写pytorch能对应上的

# 这里只能分别传入
paddle.atleast_2d(x, y)
# 下面这种方式会将 (x, y) 经过 broadcast 后作为单个输入
paddle.atleast_2d((x, y))
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

目前是 参数不一致,因为涉及到某些case的用法不同

但有点疑问:API针对这种情况为什么不和torch一致呢?broadcast 后作为单个输入是更合理的行为吗

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PaddlePaddle/Paddle#58323 (comment)

这里是与 numpy 对齐 ~

torch 的这种处理方式至少在 python 的编程习惯上存在歧义 ~

paddle.atleast_1d(*inputs)

这里本身就是处理多个输入的情况,而在 python 中,paddle.atleast_1d(x, y)paddle.atleast_1d((x, y)) 是两种不同的输入,前者是两个 positional 输入,python 的 *inputs 会展开,而后者只是一个输入,类型是 tuple 的输入 ~

后者 合适 的输入方式应该是 paddle.atleast_1d(*(x, y)),参考 numpy :

In [1]: import numpy as np

In [2]: np.atleast_1d((123, 234)) # 一个 tuple 输入
Out[2]: array([123, 234])

In [3]: np.atleast_1d((np.array(123), np.array(234))) # 一个 tuple 输入,包含两个 array
Out[3]: array([123, 234])

In [4]: np.atleast_1d(*(np.array(123), np.array(234))) # 将 tuple 展开
Out[4]: [array([123]), array([234])]

In [5]: np.atleast_1d(123, 234) # 两个输入
Out[5]: [array([123]), array([234])]

torch 之所以这么做,个人感觉是因为,这几个 api 是直接用底层 c++ 处理的,上层封装没有进行区分 ... ...

因此

broadcast 后作为单个输入是更合理的行为吗

个人感觉,不是 ~ 因为这种输入本身就不合理 ~

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PaddlePaddle/Paddle#58323 (comment)

这里是与 numpy 对齐 ~

torch 的这种处理方式至少在 python 的编程习惯上存在歧义 ~

paddle.atleast_1d(*inputs)

这里本身就是处理多个输入的情况,而在 python 中,paddle.atleast_1d(x, y)paddle.atleast_1d((x, y)) 是两种不同的输入,前者是两个 positional 输入,python 的 *inputs 会展开,而后者只是一个输入,类型是 tuple 的输入 ~

后者 合适 的输入方式应该是 paddle.atleast_1d(*(x, y)),参考 numpy :

In [1]: import numpy as np

In [2]: np.atleast_1d((123, 234)) # 一个 tuple 输入
Out[2]: array([123, 234])

In [3]: np.atleast_1d((np.array(123), np.array(234))) # 一个 tuple 输入,包含两个 array
Out[3]: array([123, 234])

In [4]: np.atleast_1d(*(np.array(123), np.array(234))) # 将 tuple 展开
Out[4]: [array([123]), array([234])]

In [5]: np.atleast_1d(123, 234) # 两个输入
Out[5]: [array([123]), array([234])]

torch 之所以这么做,个人感觉是因为,这几个 api 是直接用底层 c++ 处理的,上层封装没有进行区分 ... ...

因此

broadcast 后作为单个输入是更合理的行为吗

个人感觉,不是 ~ 因为这种输入本身就不合理 ~

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

这个是broadcast为单个输入,还是concat为单个输入?

### 参数映射
| PyTorch | PaddlePaddle | 备注 |
| ------------- | ------------ | ------------------------------------------------------ |
| <font color='red'> tensors </font> | <font color='red'> inputs </font> | 输入的 Tensor ,仅参数名不一致。 |
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

同上


PyTorch 与 Paddle 参数形式上一致,具体如下:

### 参数映射
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

同上

@zhwesky2010
Copy link
Collaborator

输入一个tuple的多个tensor,是broadcast为单个tensor,还是concat为单个tensor?具体的处理方式是什么样呢

@megemini
Copy link
Contributor Author

输入一个tuple的多个tensor,是broadcast为单个tensor,还是concat为单个tensor?具体的处理方式是什么样呢

这里之前说的不严谨,这几个 tensor 应该有一样的 shape ,而不是还需要 broadcast ~

numpy 的处理方式是 asanyarray

def atleast_1d(*arys):
    res = []
    for ary in arys:
        ary = asanyarray(ary)
...

参考 numpy 的方式,paddle 这里使用的是 to_tensor

def atleast_1d(*inputs, name=None):
    out = []
    for tensor in inputs:
        tensor = paddle.to_tensor(tensor)
...

由于 to_tensor 内部是用的是 data = np.array(data) ,因此,两者基本处理方式一样 ~

已更新文档 ~

@zhwesky2010
Copy link
Collaborator

输入一个tuple的多个tensor,是broadcast为单个tensor,还是concat为单个tensor?具体的处理方式是什么样呢

这里之前说的不严谨,这几个 tensor 应该有一样的 shape ,而不是还需要 broadcast ~

numpy 的处理方式是 asanyarray

def atleast_1d(*arys):
    res = []
    for ary in arys:
        ary = asanyarray(ary)
...

参考 numpy 的方式,paddle 这里使用的是 to_tensor

def atleast_1d(*inputs, name=None):
    out = []
    for tensor in inputs:
        tensor = paddle.to_tensor(tensor)
...

由于 to_tensor 内部是用的是 data = np.array(data) ,因此,两者基本处理方式一样 ~

已更新文档 ~

我的意思是这里如何 输入tuple时将多个Tensor处理为单个Tensor,上面的示例,并不是 多个Tenso -> 单个Tensor

@megemini
Copy link
Contributor Author

我的意思是这里如何 输入tuple时将多个Tensor处理为单个Tensor,上面的示例,并不是 多个Tenso -> 单个Tensor

In [1]: import paddle

In [2]: x = paddle.to_tensor(123)

In [3]: y = paddle.to_tensor(456)

In [4]: paddle.atleast_1d((x, y))
Out[4]: 
Tensor(shape=[2], dtype=int64, place=Place(gpu:0), stop_gradient=True,
       [123, 456])

这里的输入为 tuple,(x, y)atleast_1dtensor = paddle.to_tensor(tensor) 也就是 tensor = paddle.to_tensor((x, y)), 将 xy 这两个 tensor 组成的 tuple (x, y) 转换为一个 tensor ~

In [5]: paddle.atleast_1d(x, y)
W1122 17:33:46.747026 169531 gpu_resources.cc:119] Please NOTE: device: 0, GPU Compute Capability: 6.1, Driver API Version: 12.2, Runtime API Version: 11.7
W1122 17:33:46.750464 169531 gpu_resources.cc:164] device: 0, cuDNN Version: 8.5.
Out[5]: 
[Tensor(shape=[1], dtype=int64, place=Place(gpu:0), stop_gradient=True,
        [123]),
 Tensor(shape=[1], dtype=int64, place=Place(gpu:0), stop_gradient=True,
        [456])]

上面是分开输入的情况,是两个 tensor ~

atleast_1d 的输入有几个,输出应该就是几个 ~

如果输入是一个 tuple,输出则是这个 tuple 转为 tensor 后的结果 ~ 如果输入是多个 tensor,输出则是各个相应的结果 ~

@zhwesky2010 要不给我个例子看看?是不是我哪里解释的有问题?🤣

@zhwesky2010
Copy link
Collaborator

zhwesky2010 commented Nov 23, 2023

@megemini 所以这里的处理方式就是stack多个Tensor为单个Tensor,那就写参数不一致。但需要写明什么case下 不一致

Copy link
Collaborator

@zhwesky2010 zhwesky2010 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

需要处理下冲突


#### 多个 Tensor
```python
# Pytorch 写法
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

写不一致的case就行,这里写伪代码,不用写多了

| ------------- | ------------ | ------------------------------------------------------ |
| <font color='red'> tensors </font> | <font color='red'> inputs </font> | 输入的 Tensor ,参数不一致。 |

PyTorch 与 Paddle 功能一致,但对于多个 Tensor 输入的处理方式略有不同,具体请看转写示例。
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

这里不是多个Tensor吧,写不一致的输入case情形,其他情况两者一致。

@megemini
Copy link
Contributor Author

Update 20231124

  • 重写转写示例

请评审 ~

### 参数映射
| PyTorch | PaddlePaddle | 备注 |
| ------------- | ------------ | ------------------------------------------------------ |
| <font color='red'> tensors </font> | <font color='red'> inputs </font> | 输入的 Tensor ,参数不一致。 |
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

输入的 Tensor,仅当torch输入为tuple(Tensor)时,两者处理方式不一致,需要转写。其他情形下均一致。


此时正确的转写方式为:

```python
Copy link
Collaborator

@zhwesky2010 zhwesky2010 Nov 29, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

此行上面加一个:

####tensors: 输入为tuple(Tensor)时

然后只需要下面这两行代码,其他均删掉,转写示例 只写有差异的case,其他默认就相同 无需示例

@megemini
Copy link
Contributor Author

Update 20231129

  • 简化转写示例

请评审 ~

@@ -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)
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

有个疑问,这种多输入的Tensor,为什么会有类成员函数

Copy link
Collaborator

@zhwesky2010 zhwesky2010 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

其他地方没问题,只有个疑问,这种多输入的Tensor,为什么会有类成员函数

@megemini
Copy link
Contributor Author

其他地方没问题,只有个疑问,这种多输入的Tensor,为什么会有类成员函数

这个应该说是可变长参数,可以是多个,也可以是一个,所以个人感觉作为类成员函数应该也没什么问题?

算是个语法糖? 🤣 ~

@luotao1 luotao1 merged commit 55d19d6 into PaddlePaddle:develop Nov 29, 2023
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
contributor PaddlePaddle Hackathon 飞桨黑客松活动issue与PR
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants