【Hackathon No.10】新增 LogNormal API 的文档

docs/api/api_label

@@ -84,6 +84,7 @@ paddle.distribution.Distribution	.. _api_paddle_distribution_Distribution:
 paddle.distribution.Uniform	.. _api_paddle_distribution_Uniform:
 paddle.distribution.Categorical	.. _api_paddle_distribution_Categorical:
 paddle.distribution.Normal	.. _api_paddle_distribution_Normal:
+paddle.distribution.LogNormal	.. _api_paddle_distribution_LogNormal:
 paddle.distribution.Laplace     .. _api_paddle_distribution_Laplace:
 paddle.ParamAttr	.. _api_paddle_ParamAttr:
 paddle.static.save	.. _api_paddle_static_save:

docs/api/paddle/distribution/LogNormal_cn.rst

@@ -0,0 +1,166 @@
+.. _cn_api_distribution_Normal:
+
+LogNormal
+-------------------------------
+
+.. py:class:: paddle.distribution.LogNormal(loc, scale, name=None)
+
+
+对数正态分布
+
+.. math::
+
+    X \sim Normal(\mu, \sigma)
+
+    Y = exp(X) \sim LogNormal(\mu, \sigma)
+
+
+由于对数正态分布是基于正态分布的变换得到的分布，一般称 :math:`Normal(\mu, \sigma)` 是 :math:`LogNormal(\mu, \sigma)` 的基础分布。
+
+数学公式：
+
+概率密度函数
+
+.. math::
+
+    pdf(x; \mu, \sigma) = \frac{1}{\sigma x \sqrt{2\pi}}e^{(-\frac{(ln(x) - \mu)^2}{2\sigma^2})}
+
+上面的数学公式中：
+
+- :math:`loc = \mu`：基础正态分布的平均值；
+- :math:`scale = \sigma`：基础正态分布的标准差。
+
+参数
+::::::::::::
+
+    - **loc** (int|float|list|tuple|numpy.ndarray|Tensor) - 基础正态分布的平均值。
+    - **scale** (int|float|list|tuple|numpy.ndarray|Tensor) - 基础正态分布的标准差。
+
+代码示例
+::::::::::::
+
+
+COPY-FROM: paddle.distribution.LogNormal
+
+
+属性
+:::::::::
+
+mean
+'''''''''
+
+对数正态分布的均值
+
+variance
+'''''''''
+
+对数正态分布的方差
+
+
+方法
+:::::::::
+
+sample(shape=(), seed=0)
+'''''''''
+
+生成指定维度的样本。
+
+**参数**
+
+    - **shape** (Sequence[int], 可选) - 指定生成样本的维度。
+    - **seed** (int) - 长整型数。
+
+**返回**
+
+Tensor，预先设计好维度的样本数据。
+
+rsample(shape=())
+'''''''''
+
+重参数化采样，生成指定维度的样本。
+
+**参数**
+
+    - **shape** (Sequence[int], 可选) - 指定生成样本的维度。
+
+**返回**
+
+Tensor，预先设计好维度的样本数据。
+
+entropy()
+'''''''''
+
+信息熵
+
+数学公式：
+
+.. math::
+
+    entropy(\sigma) = 0.5 \log (2 \pi e \sigma^2) + \mu
+
+上面的数学公式中：
+
+- :math:`loc = \mu`：基础正态分布的平均值；
+- :math:`scale = \sigma`：基础正态分布的标准差。
+
+**返回**
+
+Tensor，对数正态分布的信息熵。
+
+log_prob(value)
+'''''''''
+
+对数概率密度函数
+
+**参数**
+
+    - **value** (Tensor) - 输入张量。
+
+**返回**
+
+Tensor，对数概率，数据类型与 :attr:`value` 相同。
+
+probs(value)
+'''''''''
+
+概率密度函数
+
+**参数**
+
+    - **value** (Tensor) - 输入张量。
+
+**返回**
+
+Tensor，概率，数据类型与 :attr:`value` 相同。
+
+kl_divergence(other)
+'''''''''
+
+两个对数正态分布之间的 KL 散度。
+
+数学公式：
+
+.. math::
+
+    KL\_divergence(\mu_0, \sigma_0; \mu_1, \sigma_1) = 0.5 (ratio^2 + (\frac{diff}{\sigma_1})^2 - 1 - 2 \ln {ratio})
+
+    ratio = \frac{\sigma_0}{\sigma_1}
+
+    diff = \mu_1 - \mu_0
+
+上面的数学公式中：
+
+- :math:`loc = \mu_0`：当前对数分布对应的基础分布的平均值；
+- :math:`scale = \sigma_0`：当前对数分布对应的基础分布的标准差；
+- :math:`loc = \mu_1`：另一个对数分布对应的基础分布的平均值；
+- :math:`scale = \sigma_1`：另一个对数分布对应的基础分布的标准差；
+- :math:`ratio`：两个标准差之间的比例；
+- :math:`diff`：两个平均值之间的差值。
+
+**参数**
+
+    - **other** (LogNormal) - LogNormal 的实例。
+
+**返回**
+
+Tensor，两个对数正态分布之间的 KL 散度。

docs/api/paddle/distribution/Normal_cn.rst

@@ -6,7 +6,6 @@ Normal
 .. py:class:: paddle.distribution.Normal(loc, scale, name=None)
 
 
-
 正态分布
 
 数学公式：
@@ -26,8 +25,8 @@ Normal
 参数
 ::::::::::::
 
-    - **loc** (int|float|list|numpy.ndarray|Tensor) - 正态分布平均值。数据类型为 float32 或 float64。
-    - **scale** (int|float|list|numpy.ndarray|Tensor) - 正态分布标准差。数据类型为 float32 或 float64。
+    - **loc** (int|float|list|tuple|numpy.ndarray|Tensor) - 正态分布平均值。数据类型为 float32 或 float64。
+    - **scale** (int|float|list|tuple|numpy.ndarray|Tensor) - 正态分布标准差。数据类型为 float32 或 float64。
     - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。
 
 代码示例
@@ -36,6 +35,21 @@ Normal
 
 COPY-FROM: paddle.distribution.Normal
 
+
+属性
+:::::::::
+
+mean
+'''''''''
+
+正态分布的均值
+
+variance
+'''''''''
+
+正态分布的方差
+
+
 方法
 :::::::::
 
@@ -46,13 +60,26 @@ sample(shape, seed=0)
 
 **参数**
 
-    - **shape** (list) - 1 维列表，指定生成样本的维度。数据类型为 int32。
+    - **shape** ((Sequence[int], 可选) - 指定生成样本的维度。
     - **seed** (int) - 长整型数。
 
 **返回**
 
 Tensor，预先设计好维度的 Tensor，数据类型为 float32。
 
+rsample(shape)
+'''''''''
+
+重参数化采样，生成指定维度的样本。
+
+**参数**
+
+    - **shape** ((Sequence[int], 可选) - 指定生成样本的维度。
+
+**返回**
+
+Tensor，预先设计好维度的 Tensor，数据类型为 float32。
+
 entropy()
 '''''''''
 
@@ -83,7 +110,7 @@ log_prob(value)
 
 **返回**
 
-Tensor，对数概率，数据类型与 value 相同。
+Tensor，对数概率，数据类型与 :attr:`value` 相同。
 
 probs(value)
 '''''''''

docs/api/paddle/distribution/Overview_cn.rst

@@ -31,6 +31,7 @@ paddle.distribution 目录下包含飞桨框架支持的随机变量的概率分
     " :ref:`Independent <cn_api_paddle_distribution_Independent>` ", "Independent 概率分布类"
     " :ref:`TransfomedDistribution <cn_api_paddle_distribution_TransformedDistribution>` ", "TransformedDistribution 概率分布类"
     " :ref:`Laplace <cn_api_distribution_Laplace>`", "Laplace 概率分布类"
+    " :ref:`LogNormal <cn_api_distribution_LogNormal>` ", "LogNormal 概率分布类"
 
 .. _about_distribution_transform:
 

docs/api/paddle/distribution/TransformedDistribution_cn.rst

@@ -62,3 +62,16 @@ sample(shape=())
 **返回**
 
 - Tensor：样本数据。
+
+rsample(shape=())
+'''''''''
+
+重参数化采样，生成满足特定形状的样本数据。
+
+**参数**
+
+- **shape** (Sequence[int]，可选)：采样形状。
+
+**返回**
+
+- Tensor：样本数据。