【PaddlePaddle Hackathon 第四期】No.19：为 Paddle 新增 polygamma API #472

KateJing1212 · 2023-03-20T15:03:44Z

polygamma API设计文档

zoooo0820 · 2023-03-22T07:03:43Z

rfcs/APIs/20230320_api_design_for_polygamma.md

+}
+
+```
+可以看到，`polygamma`函数调用了`polygamma_stub`函数来计算`polygamma`函数的值，`polygamma_backward`函数则用于计算梯度。实际的计算是在`polygamma_stub`函数中进行的，该函数的实现采用了CPU和CUDA两个后端，并使用了不同的算法。完整的`polygamma`函数实现涉及到多个文件和函数，包括`polygamma_stub`、`polygamma_cpu_kernel`、`polygamma_cuda_kernel`等。


从目前的代码处只能看到大致调用逻辑，但是不能明确具体的计算逻辑。

辛苦再细化一下pytorch具体计算polygamma时涉及的计算逻辑。可以分别列举下cpu / cuda的代码位置（附上链接）并简要讲解一下，方便后续对比。

zoooo0820 · 2023-03-22T07:22:03Z

rfcs/APIs/20230320_api_design_for_polygamma.md

+
+<!-- 参考：[飞桨API 设计及命名规范](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/dev_guides/api_contributing_guides/api_design_guidelines_standard_cn.html) -->
+
+API设计为 `paddle.Tensor.polygamma(n, x)`。其中 `x` 为 `B1 X ... X Bn X P X M` 张量，`n` 表示多项式 gamma 函数的导数阶数。当`n=0`时，polygamma退化为 digamma。


应该是paddle.polygamma，并支持Tensor.polygamma(n)的调用形式

从飞桨API体系一致性和易用性上来看，x应当在n前面，虽然和竞品不一致。

在这里，需要明确各个参数的情况。

x是张量，支持的数据类型有哪些。这里写出了x的shape，其中B/P/M是否有明确意义，以及是否要求x至少在3维以上。此外，Bn中的n是否与另一个参数n有关。

n是什么类型，取值范围，是否支持Tensor输入等等

根据目前api的命名规范，需要加上name

zoooo0820 · 2023-03-22T07:30:02Z

rfcs/APIs/20230320_api_design_for_polygamma.md

+
+## API实现方案
+
+该 API 实现于 python/paddle/tensor/math.py，通过调研发现，Paddle 本身已实现 paddle.digamma，可以计算gamma 函数的对数的一阶导数，可利用paddle.digamma API 做n阶导实现 paddle.polygamma。 而 Paddle 中已有 paddle.digamma API 的具体实现逻辑，位于 python/paddle/tensor/math.py 下的 digamma 函数中。


可利用paddle.digamma API 做n阶导实现 paddle.polygamma

这里需要再详细描述一下如何实现，例如是for循环实现吗，可以适当写下伪代码。需要特别注意的是，API的动静统一问题，可以验证下是否在静态图下能正常工作

zoooo0820 · 2023-03-22T07:31:37Z

rfcs/APIs/20230320_api_design_for_polygamma.md

+
+<!-- 参考：[新增API 测试及验收规范](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/dev_guides/api_contributing_guides/api_accpetance_criteria_cn.html) -->
+
+可考虑一下场景：


一下 -> 以下

zoooo0820 · 2023-03-22T07:40:05Z

rfcs/APIs/20230320_api_design_for_polygamma.md

+
+可考虑一下场景：
+
+1. 当`x` 为空张量，输出为空张量，且输出张量形状正确；


建议对测试场景整体细致描述。按以下几个模块出发

一般场景（这里额外需要注意的是，需要考虑正确值标杆如何获得，不能只是单纯因为单测引入额外的第三方包依赖）：

不同dtype的x

不同值的n

...

边界条件（较为边界但合法的值）

输入为空张量

输入n=0

...

异常测试（明确异常的原因，以及应当做出的反应）

n为不合法值时

x的shape不合理时（如果有这条限制）

...

zoooo0820 · 2023-03-22T07:43:53Z

rfcs/APIs/20230320_api_design_for_polygamma.md

+
+在 Tensorflow 中使用的 API 格式如下：
+
+`tf.math.polygamma(a, x, name=None)`[(参考API文档)](https://www.tensorflow.org/api_docs/python/tf/math/polygamma)


tf等其他框架，也辛苦像pytorch一样，明确指出一下各个参数的类型情况，这有助于最后说明最终API的设计

以上问题均已修改，请再帮忙review一下，谢谢。

zoooo0820 · 2023-03-23T03:35:38Z

rfcs/APIs/20230322_api_design_for_polygamma.md

+
+
+
+更进一步来说，在CPU上，polygamma在`torch/csrc/autograd/Functions.cpp`文件中实现[(参考链接)](https://github.com/pytorch/pytorch/blob/master/torch/csrc/autograd/function.cpp)


主要指出计算逻辑即可。这个链接里似乎没有polygamma相关的内容呢

zoooo0820 · 2023-03-23T03:36:28Z

rfcs/APIs/20230322_api_design_for_polygamma.md

+```
+其中，`polygamma_stub`是一个分派函数，它根据输入张量的设备类型和数据类型来调用不同的计算polygamma的函数。
+
+而在CUDA上，polygamma在`torch/csrc/cuda/ElementWise.cu`文件中实现[(参考链接)](https://github.com/pytorch/pytorch/blob/master/torch/csrc/autograd/function.cpp)


此处链接有误

zoooo0820 · 2023-03-23T03:39:05Z

rfcs/APIs/20230322_api_design_for_polygamma.md

+  return iter.output();
+}
+```
+其中，`calc_polygamma`是一个计算polygamma的辅助函数，`factorial`是计算阶乘的辅助函数。在CUDA中，`PolyGammaOp`是一个functor，用于计算polygamma。`gpu_kernel`是一个PyTorch封装的CUDA kernel，用于在GPU上并行地计算polygamma。


上段代码中未出现calc_polygamma的调用呢。此外，作为核心计算逻辑，calc_polygamma也辛苦展示并简单介绍一下吧

zoooo0820 · 2023-03-23T03:44:19Z

rfcs/APIs/20230322_api_design_for_polygamma.md

+
+<!-- 参考：[飞桨API 设计及命名规范](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/dev_guides/api_contributing_guides/api_design_guidelines_standard_cn.html) -->
+
+API设计为 `paddle.polygamma(x, n, name)`。


name=None，默认值需要给出；

另外需要明确指出，同时支持Tensor.polygamma(n)的调用形式

zoooo0820 · 2023-03-23T03:50:37Z

rfcs/APIs/20230322_api_design_for_polygamma.md

+<!-- 参考：[飞桨API 设计及命名规范](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/dev_guides/api_contributing_guides/api_design_guidelines_standard_cn.html) -->
+
+API设计为 `paddle.polygamma(x, n, name)`。
+其中 `x` 为非负值张量，允许的数据类型是float32和float64。`n` 表示多项式 gamma 函数的导数阶数，其为一个与 `x` 数据类型相同的张量。当`n=0`时，polygamma退化为 digamma。`name` 作为可选参数，定义了该操作的名称。


x是否需要限制非负输入呢，在其他框架的文档中似乎没有看到这个限制。此外，这里可以指出一下，只支持fp32/fp64的原因是因为digamma限制。

n应当支持int类型；此外，如果n可以支持Tensor类型输入，其也应当是int32/int64型。这里与x同类型不适合，因为这个API并不是一个二元计算，看起来TF的设计不是特别合理。此外，需要指出n的取值范围

name需要指出默认值。

zoooo0820 · 2023-03-23T04:02:45Z

rfcs/APIs/20230322_api_design_for_polygamma.md

+
+# 二、飞桨现状
+
+对飞桨框架目前不支持此功能，但支持 digamma 函数[(参考API文档)](https://www.paddlepaddle.org.cn/documentation/docs/zh/api/paddle/digamma_cn.html) ，且支持输入为张量。digamma 函数是 gamma 函数的对数的一阶导数，k 阶的 polygamma 函数是 gamma 函数的对数的 (k + 1) 阶导数。


多了第一个“对”字，小语病

以上问题均已修改，请再帮忙review一下，谢谢。

zoooo0820 · 2023-03-23T09:20:45Z

rfcs/APIs/20230323_api_design_for_polygamma.md

+<!-- 参考：[飞桨API 设计及命名规范](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/dev_guides/api_contributing_guides/api_design_guidelines_standard_cn.html) -->
+
+API设计为 `paddle.polygamma(x, n, name=None)`。
+其中 `x` 为张量，允许的数据类型是float32和float64，其原因是digamma对数据类型进行了限制。`n` 表示多项式 gamma 函数的导数阶数，其为一个非负值张量，允许的数据类型是int32和int64。当`n=0`时，polygamma退化为 digamma。`name` 作为可选参数，定义了该操作的名称。


这个地方还有点问题
1.n，int类型是必须支持的。（如果需要额外支持张量输入的话，这里应当是int32/int64的数据类型，且需要额外考虑下是否对张量的维度ndim/元素数量numel做限制）
2.name是可选参数，定义了该操作的名称，默认值是None

zoooo0820 · 2023-03-23T09:21:34Z

rfcs/APIs/20230323_api_design_for_polygamma.md

+
+API设计为 `paddle.polygamma(x, n, name=None)`。
+其中 `x` 为张量，允许的数据类型是float32和float64，其原因是digamma对数据类型进行了限制。`n` 表示多项式 gamma 函数的导数阶数，其为一个非负值张量，允许的数据类型是int32和int64。当`n=0`时，polygamma退化为 digamma。`name` 作为可选参数，定义了该操作的名称。
+另外，该API还支持`paddle.polygamma(n)`的调用形式。


另外，该API还支持paddle.polygamma(n)的调用形式。

应当是还支持Tensor.polygamma(n)

以上问题均已修改，请再帮忙review一下，谢谢。

zoooo0820 · 2023-03-23T13:05:04Z

rfcs/APIs/20230323_api_design_for_polygamma.md

+
+API设计为 `paddle.polygamma(x, n, name=None)`。
+`x` 为张量，允许的数据类型是float32和float64，其原因是digamma对数据类型进行了限制。
+`n` 表示多项式 gamma 函数的导数阶数，其可以为一个非负整数或一个非负值张量，允许的数据类型是int32和int64；如果`n`是一个张量，需要保证其形状与`x`相同，即维度与`x`相同或是其子集，且元素数量与`x`相同；当`n=0`时，polygamma退化为 digamma。


这并非一个二元计算的API，如果n为张量，形状与元素数量需要和x相同的目的是什么呢，是否应当是ndim<=1 && numel==1呢。这里可以调研下同样支持Tensor输入的TF的情况

已修改，请再帮忙review一下，谢谢。

zoooo0820 · 2023-03-24T02:48:03Z

rfcs/APIs/20230323_api_design_for_polygamma.md

@@ -4,7 +4,7 @@
 |---|---|
 |提交作者<input type="checkbox" class="rowselector hidden"> | 吃点儿好的 [paddle](https://github.com/KateJing1212/community) | 
 |提交时间<input type="checkbox" class="rowselector hidden"> | 2023-03-23 | 
-|版本号 | V4.0 | 
+|版本号 | V5.0 | 


这里就按1.0就好了，未实际合入生效的不算版本修改

已修改，请再帮忙review一下，谢谢

zoooo0820

LGTM

Ligoml · 2023-04-27T06:12:10Z

开发者你好，想了解下现在的开发进度，如果遇到什么卡点和问题，欢迎加群沟通~

KateJing1212 and others added 3 commits March 20, 2023 22:11

Create 20220320_api_design_for_polygamma.md

56b50f6

Create 20230320_api_design_for_polygamma.md

6a33165

apidoctest

d7342d5

KateJing1212 mentioned this pull request Mar 20, 2023

【PaddlePaddle Hackathon 第四期】任务总览 PaddlePaddle/Paddle#51281

Closed

paddle-bot bot added the contributor label Mar 20, 2023

luotao1 assigned luotao1, zoooo0820 and Ligoml Mar 22, 2023

zoooo0820 reviewed Mar 22, 2023

View reviewed changes

review0322

16d8ace

zoooo0820 reviewed Mar 23, 2023

View reviewed changes

review0323

6dd250f

zoooo0820 reviewed Mar 23, 2023

View reviewed changes

'review0323(2)'

adf1861

zoooo0820 reviewed Mar 23, 2023

View reviewed changes

'review0323(3)'

2d23910

zoooo0820 reviewed Mar 24, 2023

View reviewed changes

'review0324'

1327a3c

zoooo0820 approved these changes Mar 24, 2023

View reviewed changes

zoooo0820 merged commit 0773157 into PaddlePaddle:master Mar 24, 2023

PommesPeter mentioned this pull request May 14, 2023

【Hackathon 4 No.19】Add polygamma API to Paddle PaddlePaddle/Paddle#53791

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

【PaddlePaddle Hackathon 第四期】No.19：为 Paddle 新增 polygamma API #472

【PaddlePaddle Hackathon 第四期】No.19：为 Paddle 新增 polygamma API #472

KateJing1212 commented Mar 20, 2023

zoooo0820 Mar 22, 2023

zoooo0820 Mar 22, 2023

zoooo0820 Mar 22, 2023

zoooo0820 Mar 22, 2023

zoooo0820 Mar 22, 2023

zoooo0820 Mar 22, 2023

KateJing1212 Mar 22, 2023

zoooo0820 Mar 23, 2023

zoooo0820 Mar 23, 2023

zoooo0820 Mar 23, 2023

zoooo0820 Mar 23, 2023

zoooo0820 Mar 23, 2023

zoooo0820 Mar 23, 2023

KateJing1212 Mar 23, 2023

zoooo0820 Mar 23, 2023

zoooo0820 Mar 23, 2023

KateJing1212 Mar 23, 2023

zoooo0820 Mar 23, 2023

KateJing1212 Mar 23, 2023

zoooo0820 Mar 24, 2023

KateJing1212 Mar 24, 2023

zoooo0820 left a comment

Ligoml commented Apr 27, 2023


		<!-- 参考：[飞桨API 设计及命名规范](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/dev_guides/api_contributing_guides/api_design_guidelines_standard_cn.html) -->

		API设计为 `paddle.Tensor.polygamma(n, x)`。其中 `x` 为 `B1 X ... X Bn X P X M` 张量，`n` 表示多项式 gamma 函数的导数阶数。当`n=0`时，polygamma退化为 digamma。


		## API实现方案

		该 API 实现于 python/paddle/tensor/math.py，通过调研发现，Paddle 本身已实现 paddle.digamma，可以计算gamma 函数的对数的一阶导数，可利用paddle.digamma API 做n阶导实现 paddle.polygamma。而 Paddle 中已有 paddle.digamma API 的具体实现逻辑，位于 python/paddle/tensor/math.py 下的 digamma 函数中。


		<!-- 参考：[新增API 测试及验收规范](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/dev_guides/api_contributing_guides/api_accpetance_criteria_cn.html) -->

		可考虑一下场景：


		可考虑一下场景：

		1. 当`x` 为空张量，输出为空张量，且输出张量形状正确；


		在 Tensorflow 中使用的 API 格式如下：

		`tf.math.polygamma(a, x, name=None)`[(参考API文档)](https://www.tensorflow.org/api_docs/python/tf/math/polygamma)




		更进一步来说，在CPU上，polygamma在`torch/csrc/autograd/Functions.cpp`文件中实现[(参考链接)](https://github.com/pytorch/pytorch/blob/master/torch/csrc/autograd/function.cpp)


		<!-- 参考：[飞桨API 设计及命名规范](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/dev_guides/api_contributing_guides/api_design_guidelines_standard_cn.html) -->

		API设计为 `paddle.polygamma(x, n, name)`。


		# 二、飞桨现状

		对飞桨框架目前不支持此功能，但支持 digamma 函数[(参考API文档)](https://www.paddlepaddle.org.cn/documentation/docs/zh/api/paddle/digamma_cn.html) ，且支持输入为张量。digamma 函数是 gamma 函数的对数的一阶导数，k 阶的 polygamma 函数是 gamma 函数的对数的 (k + 1) 阶导数。

【PaddlePaddle Hackathon 第四期】No.19：为 Paddle 新增 polygamma API #472

【PaddlePaddle Hackathon 第四期】No.19：为 Paddle 新增 polygamma API #472

Conversation

KateJing1212 commented Mar 20, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

zoooo0820 left a comment

Choose a reason for hiding this comment

Ligoml commented Apr 27, 2023