【Hackathon 5th No. 18】Add Binomial and Poisson API (#6325)

Author: NKNaN

docs/api/paddle/distribution/Binomial_cn.rst

@@ -0,0 +1,127 @@
+.. _cn_api_paddle_distribution_Binomial:
+
+Binomial
+-------------------------------
+
+.. py:class:: paddle.distribution.Binomial(total_count, probs)
+
+
+在概率论和统计学中，Binomial 是一种最基本的离散型概率分布，定义在 :math:`[0, n] \cap \mathbb{N}` 上，可以看作是扔一枚硬币（可能是不公平的硬币）被扔出正面的次数，
+它的随机变量的取值可以看作是一系列独立的伯努利实验结果的总和。
+
+其概率质量函数（pmf）为：
+
+.. math::
+
+    pmf(x; n, p) = \frac{n!}{x!(n-x)!}p^{x}(1-p)^{n-x}
+
+其中：
+
+- :math:`n` 表示伯努利实验次数。
+- :math:`p` 表示每次伯努利实验中事件发生的概率。
+
+参数
+:::::::::
+
+    - **total_count** (int|Tensor) - 即上述公式中 :math:`n` 参数，大于零，表示伯努利实验次数。如果 :attr:`total_count` 的输入数据类型是 int 则会被转换
+      成数据类型为 paddle 全局默认数据类型的 1-D Tensor，否则将转换成与 :attr:`probs` 相同的数据类型。
+
+    - **probs** (float|Tensor) - 即上述公式中 :math:`p` 参数，在 [0, 1] 区间内，表示每次伯努利实验中事件发生的概率。如果 :attr:`probs` 的输
+      入数据类型是 float 则会被转换为 paddle 全局默认数据类型的 1-D Tensor。
+
+
+代码示例
+:::::::::
+
+COPY-FROM: paddle.distribution.Binomial
+
+属性
+:::::::::
+
+mean
+'''''''''
+
+Binomial 分布的均值
+
+**返回**
+
+Tensor，均值
+
+variance
+'''''''''
+
+Binomial 分布的方差
+
+**返回**
+
+Tensor，方差
+
+方法
+:::::::::
+
+prob(value)
+'''''''''
+
+计算 value 的概率。
+
+**参数**
+
+    - **value** (Tensor) - 待计算值。
+
+**返回**
+
+Tensor，value 的概率。数据类型与 :attr:`probs` 相同。
+
+
+log_prob(value)
+'''''''''
+
+计算 value 的对数概率。
+
+**参数**
+
+    - **value** (Tensor) - 待计算值。
+
+**返回**
+
+Tensor，value 的对数概率。数据类型与 :attr:`probs` 相同。
+
+
+sample()
+'''''''''
+
+从 Binomial 分布中生成满足特定形状的样本数据。最终生成样本形状为 ``shape+batch_shape`` 。
+
+**参数**
+
+    - **shape** (Sequence[int]，可选)：采样次数。
+
+**返回**
+
+Tensor：样本数据。其维度为 :math:`\text{sample shape} + \text{batch shape}` 。
+
+entropy()
+'''''''''
+
+计算 Binomial 分布的信息熵。
+
+.. math::
+
+    \mathcal{H}(X) = - \sum_{x \in \Omega} p(x) \log{p(x)}
+
+**返回**
+
+类别分布的信息熵，数据类型与 :attr:`probs` 相同。
+
+kl_divergence(other)
+'''''''''
+
+相对于另一个类别分布的 KL 散度，两个分布需要有相同的 :attr:`total_count`。
+
+**参数**
+
+    - **other** (Binomial) - 输入的另一个类别分布。
+
+**返回**
+
+相对于另一个类别分布的 KL 散度，数据类型与 :attr:`probs` 相同。

docs/api/paddle/distribution/Overview_cn.rst

@@ -23,6 +23,7 @@ paddle.distribution 目录下包含飞桨框架支持的随机变量的概率分
     " :ref:`Distribution <cn_api_paddle_distribution_Distribution>` ", "Distribution 概率分布抽象基类"
     " :ref:`ExponentialFamily <cn_api_paddle_distribution_ExponentialFamily>` ", "ExponentialFamily 指数型分布族基类"
     " :ref:`Bernoulli <cn_api_paddle_distribution_Bernoulli>` ", "Bernoulli 概率分布类"
+    " :ref:`Binomial <cn_api_paddle_distribution_Binomial>` ", "Binomial 概率分布类"
     " :ref:`ContinuousBernoulli <cn_api_paddle_distribution_ContinuousBernoulli>` ", "ContinuousBernoulli 概率分布类"
     " :ref:`Categorical <cn_api_paddle_distribution_Categorical>` ", "Categorical 概率分布类"
     " :ref:`Cauchy <cn_api_paddle_distribution_Cauchy>` ", "Cauchy 概率分布类"
@@ -36,6 +37,7 @@ paddle.distribution 目录下包含飞桨框架支持的随机变量的概率分
     " :ref:`TransfomedDistribution <cn_api_paddle_distribution_TransformedDistribution>` ", "TransformedDistribution 概率分布类"
     " :ref:`Laplace <cn_api_paddle_distribution_Laplace>`", "Laplace 概率分布类"
     " :ref:`LogNormal <cn_api_paddle_distribution_LogNormal>` ", "LogNormal 概率分布类"
+    " :ref:`Poisson <cn_api_paddle_distribution_Poisson>` ", "Poisson 概率分布类"
     " :ref:`Gumbel <cn_api_paddle_distribution_Gumbel>` ", "Gumbel 概率分布类"
     " :ref:`Geometric <cn_api_paddle_distribution_Geometric>` ", "Geometric 概率分布类"
 

docs/api/paddle/distribution/Poisson_cn.rst

@@ -0,0 +1,120 @@
+.. _cn_api_paddle_distribution_Poisson:
+
+Poisson
+-------------------------------
+
+.. py:class:: paddle.distribution.Poisson(rate)
+
+
+在概率论和统计学中，Poisson 是一种最基本的离散型概率分布，定义在非负整数集上，用来描述单位时间内随机事件发生次数的概率分布。
+
+其概率质量函数（pmf）为：
+
+.. math::
+
+    pmf(x; \lambda) = \frac{e^{-\lambda} \cdot \lambda^x}{x!}
+
+其中，:math:`\lambda` 表示事件平均发生率。
+
+
+参数
+:::::::::
+
+    - **rate** (int|float|Tensor) - 即上述公式中 :math:`\lambda` 参数，大于零，表示事件平均发生率，即单位时间内的事件发生次数。如果输入数据类型不是 int 或 float
+      :attr:`rate` 的数据类型会被转换成数据类型为 paddle 全局默认数据类型的 1-D Tensor
+
+代码示例
+:::::::::
+
+COPY-FROM: paddle.distribution.Poisson
+
+属性
+:::::::::
+
+mean
+'''''''''
+
+Poisson 分布的均值
+
+**返回**
+
+Tensor，均值
+
+variance
+'''''''''
+
+Poisson 分布的方差
+
+**返回**
+
+Tensor，方差
+
+方法
+:::::::::
+
+prob(value)
+'''''''''
+
+计算 value 的概率。
+
+**参数**
+
+    - **value** (Tensor) - 待计算值。
+
+**返回**
+
+Tensor，value 的概率。数据类型与 :attr:`rate` 相同。
+
+
+log_prob(value)
+'''''''''
+
+计算 value 的对数概率。
+
+**参数**
+
+    - **value** (Tensor) - 待计算值。
+
+**返回**
+
+Tensor，value 的对数概率。数据类型与 :attr:`rate` 相同。
+
+
+sample()
+'''''''''
+
+从 Poisson 分布中生成满足特定形状的样本数据。最终生成样本形状为 ``shape+batch_shape`` 。
+
+**参数**
+
+    - **shape** (Sequence[int]，可选)：采样次数。
+
+**返回**
+
+Tensor，样本数据。其维度为 :math:`\text{sample shape} + \text{batch shape}` 。
+
+entropy()
+'''''''''
+
+计算 Poisson 分布的信息熵。
+
+.. math::
+
+    \mathcal{H}(X) = - \sum_{x \in \Omega} p(x) \log{p(x)}
+
+**返回**
+
+类别分布的信息熵，数据类型与 :attr:`rate` 相同。
+
+kl_divergence(other)
+'''''''''
+
+相对于另一个类别分布的 KL 散度，两个分布需要有相同的 :math:`\text{batch shape}`。
+
+**参数**
+
+    - **other** (Poisson) - 输入的另一个类别分布。
+
+**返回**
+
+相对于另一个类别分布的 KL 散度，数据类型与 :attr:`rate` 相同。