【Hackathon 6th No.11】Add log_normal and log_normal_ API to Paddle (#6664)

* add lognormal

* update

* update

* update

* delete log_normal in tensor overview_en

* update lognormal

Author: NKNaN

docs/api/paddle/Overview_cn.rst

@@ -225,6 +225,7 @@ tensor 数学操作原位（inplace）版本
     " :ref:`paddle.index_fill_ <cn_api_paddle_index_fill_>` ", "Inplace 版本的 index_fill API，对输入 x 采用 Inplace 策略"
     " :ref:`paddle.bitwise_left_shift_ <cn_api_paddle_bitwise_left_shift_>` ", "Inplace 版本的 bitwise_left_shift API，对输入 x 采用 Inplace 策略"
     " :ref:`paddle.bitwise_right_shift_ <cn_api_paddle_bitwise_right_shift_>` ", "Inplace 版本的 bitwise_right_shift API，对输入 x 采用 Inplace 策略"
+    " :ref:`paddle.log_normal_ <cn_api_paddle_log_normal_>` ", "Inplace 版本的 log_normal API，对输入 x 采用 Inplace 策略"
 
 
 .. _tensor_logic:
@@ -345,6 +346,7 @@ tensor random 相关
 
     " :ref:`paddle.bernoulli <cn_api_paddle_bernoulli>` ", "以输入 x 为概率，生成一个伯努利分布（0-1 分布）的 Tensor，输出 Tensor 的形状和数据类型与输入 x 相同"
     " :ref:`paddle.binomial <cn_api_paddle_binomial>` ", "以输入 count 为总实验次数， prob 为实验成功的概率，生成一个二项分布的 Tensor"
+    " :ref:`paddle.log_normal <cn_api_paddle_log_normal>` ", "返回符合对数正态分布（对应正态分布的均值为 mean ，标准差为 std）的随机 Tensor"
     " :ref:`paddle.multinomial <cn_api_paddle_multinomial>` ", "以输入 x 为概率，生成一个多项分布的 Tensor"
     " :ref:`paddle.normal <cn_api_paddle_normal>` ", "返回符合正态分布（均值为 mean ，标准差为 std 的正态随机分布）的随机 Tensor"
     " :ref:`paddle.rand <cn_api_paddle_rand>` ", "返回符合均匀分布的，范围在[0, 1)的 Tensor"

docs/api/paddle/Tensor/Overview_en.rst

@@ -173,6 +173,7 @@ Methods
     logical_not
     logical_or
     logical_xor
+    log_normal_
     logsumexp
     masked_select
     matmul

docs/api/paddle/Tensor_cn.rst

@@ -1675,6 +1675,11 @@ logsumexp(axis=None, keepdim=False, name=None)
 
 返回类型：Tensor
 
+log_normal_(mean=0.0, std=1.0, name=None)
+:::::::::
+
+Inplace 版本的 :ref:`cn_api_paddle_log_normal` API，对输入 `x` 采用 Inplace 策略。
+
 请参考 :ref:`cn_api_paddle_logsumexp`
 
 masked_select(mask, name=None)

docs/api/paddle/log_normal__cn.rst

@@ -0,0 +1,12 @@
+.. _cn_api_paddle_log_normal_:
+
+log\_normal\_
+-------------------------------
+
+.. py:function:: paddle.log_normal_(x, mean=1.0, std=2.0, name=None)
+
+Inplace 版本的 :ref:`cn_api_paddle_log_normal` API，对输入 `x` 采用 Inplace 策略。
+
+更多关于 inplace 操作的介绍请参考 `3.1.3 原位（Inplace）操作和非原位操作的区别`_ 了解详情。
+
+.. _3.1.3 原位（Inplace）操作和非原位操作的区别: https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/guides/beginner/tensor_cn.html#id3

docs/api/paddle/log_normal_cn.rst

@@ -0,0 +1,40 @@
+.. _cn_api_paddle_log_normal:
+
+log\_normal
+-------------------------------
+
+.. py:function:: paddle.log_normal(mean=1.0, std=2.0, shape=None, name=None)
+
+
+返回符合对数正态分布（对应正态分布的均值为 ``mean``，标准差为 ``std``）的随机 Tensor，对数正态分布的分布函数如下
+
+.. math::
+
+    f(x) = \frac{1}{x\sigma\sqrt{2\pi}}e^{-\frac{(\ln{x}-\mu)^2}{2\sigma^2}}
+
+其中：
+
+- :math:`mu` 表示对应正态分布的平均值。
+- :math:`sigma` 表示对应正态分布的标准差。
+
+如果 ``mean`` 是 Tensor，则输出 Tensor 和 ``mean`` 具有相同的形状和数据类型。
+如果 ``mean`` 不是 Tensor，且 ``std`` 是 Tensor，则输出 Tensor 和 ``std`` 具有相同的形状和数据类型。
+如果 ``mean`` 和 ``std`` 都不是 Tensor，则输出 Tensor 的形状为 ``shape``，数据类型为 float32。
+如果 ``mean`` 和 ``std`` 都是 Tensor，则 ``mean`` 和 ``std`` 的元素个数应该相同。
+
+参数
+::::::::::
+
+  - **mean** (float|Tensor，可选) - 输出 Tensor 对应正态分布的平均值。如果 ``mean`` 是 float，则表示输出 Tensor 中所有元素的正态分布的平均值。如果 ``mean`` 是 Tensor (支持的数据类型为 float32、float64)，则表示输出 Tensor 中每个元素对应正态分布的平均值。默认值为 1.0。
+  - **std** (float|Tensor，可选) - 输出 Tensor 对应正态分布的标准差。如果 ``std`` 是 float，则表示输出 Tensor 中所有元素的正态分布的标准差。如果 ``std`` 是 Tensor (支持的数据类型为 float32、float64)，则表示输出 Tensor 中每个元素对应正态分布的标准差。默认值为 2.0。
+  - **shape** (list|tuple|Tensor，可选) - 生成的随机 Tensor 的形状。如果 ``shape`` 是 list、tuple，则其中的元素可以是 int，或者是形状为[]且数据类型为 int32、int64 的 0-D Tensor。如果 ``shape`` 是 Tensor，则是数据类型为 int32、int64 的 1D Tensor。如果 ``mean`` 或者 ``std`` 是 Tensor，输出 Tensor 的形状和 ``mean`` 或者 ``std`` 相同(此时 ``shape`` 无效)。默认值为 None。
+  - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。
+
+返回
+::::::::::
+  Tensor，符合对数正态分布（对应正态分布的均值为 ``mean``，标准差为 ``std``）的随机 Tensor。
+
+示例代码
+::::::::::
+
+COPY-FROM: paddle.log_normal

docs/guides/model_convert/convert_from_pytorch/api_difference/Tensor/torch.Tensor.log_normal_.md

@@ -0,0 +1,33 @@
+## [ torch 参数更多 ]torch.Tensor.log_normal_
+
+### [torch.Tensor.log_normal_](https://pytorch.org/docs/stable/generated/torch.Tensor.log_normal_.html#torch-tensor-log-normal)
+
+```python
+torch.Tensor.log_normal_(mean=1, std=2, *, generator=None)
+```
+
+### [paddle.Tensor.log_normal_](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/api/paddle/Tensor_cn.html#log_normal-mean-1-0-std-2-0-shape-none-name-none)
+
+```python
+paddle.Tensor.log_normal_(mean=1.0, std=2.0, name=None)
+```
+
+PyTorch 相比 Paddle 支持更多其他参数，具体如下：
+
+### 参数映射
+
+| PyTorch       | PaddlePaddle | 备注                                                                                |
+| ------------- | ------------ | ----------------------------------------------------------------------------------- |
+| generator     | -            | 用于采样的伪随机数生成器， Paddle 无此参数，一般对网络训练结果影响不大，可直接删除。    |
+
+### 转写示例
+
+```python
+# torch 写法
+x = torch.randn(2, 3)
+y = x.log_normal_()
+
+# paddle 写法
+x = paddle.randn([2, 3])
+y = x.log_normal_()
+```