【Hackathon 5th No.10】 为 Paddle 新增 bernoulli_ / log_normal_ / log_norm…

rfcs/APIs/20230917_api_design_for_bernoulli_lognormal.md

@@ -0,0 +1,67 @@
+
+|API名称 | bernoulli_ / log_normal_ / log_normal | 
+|---|---|
+|提交作者 | [您的名字] | 
+|提交时间 | 2023-09-17 | 
+|版本号 | V1.0 | 
+|依赖飞桨版本 | develop版本 | 
+|文件名 | 20230917_api_design_for_bernoulli_lognormal.md |
+
+# 一、概述
+
+## 1、相关背景
+随着深度学习技术的广泛应用，统计分布，特别是伯努利和对数正态分布，在模型初始化、正则化和其他场景中都有广泛的应用。为了让Paddle用户更方便地实现这些功能，我们提议添加这些API。
+
+## 2、功能目标
+1. 实现指定概率p的伯努利分布。
+2. 实现指定均值和方差的对数正态分布。
+3. 两种分布都需要提供in-place和非in-place版本。
+
+## 3、意义
+- 提供更丰富的概率分布工具，满足广泛的应用需求。
+- 对齐其他主流深度学习框架的功能，增强Paddle的竞争力。
+
+# 二、飞桨现状
+Paddle目前支持一系列的随机分布生成API，但伯努利和对数正态分布仍然缺失。尽管可以通过组合其他API间接实现，但直接的支持将更加方便。
+
+# 三、业内方案调研
+
+在业界的其他主流深度学习框架中，伯努利分布和对数正态分布API都是标准的组成部分，具体如下：
+
+## TensorFlow
+- TensorFlow提供了`tf.random.bernoulli`函数来生成伯努利分布。该函数允许用户指定概率和输出张量的形状。
+- 对于对数正态分布，TensorFlow提供了`tf.random.log_normal`函数。用户可以指定均值、标准差以及输出张量的形状。
+
+## PyTorch
+- PyTorch通过`torch.bernoulli`函数支持伯努利分布的生成。该函数可以接收一个张量作为概率参数，并返回一个同形状的输出张量。
+- 对于对数正态分布，PyTorch提供了`torch.distributions.LogNormal`类。这是一个更加复杂的API，不仅可以生成随机数，还提供了其他统计功能如PDF和CDF计算。
+
+### 应用情况
+在实际应用中，伯努利分布和对数正态分布被用于多种场景，如模型初始化、数据增强和特定类型的噪音注入。考虑到这些API在TensorFlow和PyTorch中的广泛使用，它们被认为是深度学习库中的基本组件。
+
+
+# 四、对比分析
+与TensorFlow和PyTorch相比，Paddle的API设计通常更加灵活和高效。通过新增这些API，Paddle可以提供与其他主流框架相当的功能，并在性能和易用性上可能有所优势。
+
+# 五、设计思路与实现方案
+
+## 命名与参数设计
+- `paddle.bernoulli_`: 伯努利分布的in-place版本。
+- `paddle.Tensor.bernoulli_`: Tensor方法版本。
+- `paddle.log_normal_`: 对数正态分布的in-place版本。
+- `paddle.Tensor.log_normal_`: Tensor方法版本。
+- `paddle.log_normal`: 对数正态分布的非in-place版本。
+
+## 底层OP设计
+- `bernoulli_`可以通过`paddle.uniform_`来实现。
+- `log_normal_`和`log_normal`可以通过`paddle.normal_`和`paddle.exp_`组合来实现。
+
+## API实现方案
+- 在`paddle/tensor/random.py`中实现Python API。
+- 在`paddle/fluid/operators`中实现底层C++ OP。
+
+# 六、测试和验收的考量
+- 对所有新API进行严格的单元测试。
+- 对性能进行基准测试，确保与其他框架相当或更好。
+- 提供详细的API文档和示例。
+