【Hackathon 5th No.19】Add ContinuousBernoulli and MultivariateNormal API

docs/api/paddle/distribution/ContinuousBernoulli_cn.rst

@@ -0,0 +1,205 @@
+.. _cn_api_paddle_distribution_ContinuousBernoulli:
+
+ContinuousBernoulli
+-------------------------------
+
+.. py:class:: paddle.distribution.ContinuousBernoulli(probs, lims=(0.499, 0.501))
+
+
+ContinuousBernoulli 是一种定义在 [0，1] 区间上的连续型概率分布，参数 :attr:`probs` 描述了其概率密度函数的形状。它可以被视为连续型的伯努利分布。
+出自 `The continuous Bernoulli: fixing a pervasive error in variational autoencoders. <https://arxiv.org/abs/1907.06845>`_
+
+其概率密度函数（pdf）为：
+
+.. math::
+
+    p(x;\lambda) = C(\lambda)\lambda^x (1-\lambda)^{1-x}
+
+其中：
+
+- :math:`x` 在 [0, 1] 区间内是连续的。
+- :math:`\lambda` 表示事件发生的概率。
+- :math:`C(\lambda)` 表示归一化常数因子，表达式如下：
+
+.. math::
+
+    {   C(\lambda) =
+        \left\{
+        \begin{aligned}
+        &2 & \text{ if $\lambda = \frac{1}{2}$} \\
+        &\frac{2\tanh^{-1}(1-2\lambda)}{1 - 2\lambda} & \text{ otherwise}
+        \end{aligned}
+        \right. }
+
+参数
+:::::::::
+
+    - **probs** (int|float|Tensor) - 即上述公式中 :math:`\lambda` 参数，在 [0, 1] 内，刻画 ContinuousBernoulli 分布的
+      概率密度函数的形状。如果 :attr:`probs` 的输入数据类型是 `int` 或 `float` ，则会被转换为数据类型为 paddle 全局默认数据类型的 1-D Tensor。
+
+    - **lims** (tuple) - 表示概率计算非稳定区域的区域宽度，非稳定区域的概率计算使用泰勒展开做近似。默认值为 (0.499, 0.501)。
+
+代码示例
+:::::::::
+
+COPY-FROM: paddle.distribution.ContinuousBernoulli
+
+属性
+:::::::::
+
+mean
+'''''''''
+
+ContinuousBernoulli 分布的均值
+
+**返回**
+
+Tensor，均值
+
+variance
+'''''''''
+
+ContinuousBernoulli 分布的方差
+
+**返回**
+
+Tensor，方差
+
+方法
+:::::::::
+
+prob(value)
+'''''''''
+
+计算 :attr:`value` 的概率。
+
+**参数**
+
+    - **value** (Tensor) - 待计算值。
+
+**返回**
+
+Tensor，:attr:`value` 的概率。数据类型与 `self.probs` 相同。
+
+
+log_prob(value)
+'''''''''
+
+计算 value 的对数概率。
+
+**参数**
+
+    - **value** (Tensor) - 待计算值。
+
+**返回**
+
+Tensor，:attr:`value` 的对数概率。数据类型与 `self.probs` 相同。
+
+
+cdf(value)
+'''''''''
+
+计算 :attr:`value` 的累计分布 quantile 值。
+
+.. math::
+
+    {   P(X \le t; \lambda) =
+        F(t;\lambda) =
+        \left\{
+        \begin{aligned}
+        &t & \text{ if $\lambda = \frac{1}{2}$} \\
+        &\frac{\lambda^t (1 - \lambda)^{1 - t} + \lambda - 1}{2\lambda - 1} & \text{ otherwise}
+        \end{aligned}
+        \right. }
+
+**参数**
+
+    - **value** (Tensor) - 待计算值。
+
+**返回**
+
+Tensor: :attr:`value` 的累积分布函数对应的 quantile 值。数据类型与 `self.probs` 相同。
+
+
+icdf(value)
+'''''''''
+
+计算 value 的逆累计分布值。
+
+.. math::
+
+    {   F^{-1}(x;\lambda) =
+        \left\{
+        \begin{aligned}
+        &x & \text{ if $\lambda = \frac{1}{2}$} \\
+        &\frac{\log(1+(\frac{2\lambda - 1}{1 - \lambda})x)}{\log(\frac{\lambda}{1-\lambda})} & \text{ otherwise}
+        \end{aligned}
+        \right. }
+
+**参数**
+
+    - **value** (Tensor) - 待计算 quantile。
+
+**返回**
+
+Tensor，ContinuousBernoulli 随机变量在对应 quantile 下的值。数据类型与 `self.probs` 相同。
+
+
+sample(shape=())
+'''''''''
+
+从 ContinuousBernoulli 分布中生成满足特定形状的样本数据。最终生成样本形状为 ``shape+batch_shape`` 。
+
+**参数**
+
+    - **shape** (Sequence[int]，可选)：采样次数。
+
+**返回**
+
+Tensor，样本数据。其维度为 :math:`\text{sample shape} + \text{batch shape}` 。
+
+
+rsample(shape=())
+'''''''''
+
+重参数化采样，生成指定维度的样本。最终生成样本形状为 ``shape+batch_shape`` 。
+
+**参数**
+
+    - **shape** (Sequence[int]，可选)：采样次数。
+
+**返回**
+
+Tensor：样本数据。其维度为 :math:`\text{sample shape} + \text{batch shape}` 。
+
+
+entropy()
+'''''''''
+
+计算 ContinuousBernoulli 分布的信息熵。
+
+.. math::
+
+    \mathcal{H}(X) = -\log C + \left[ \log (1 - \lambda) -\log \lambda \right] \mathbb{E}(X)  - \log(1 - \lambda)
+
+**返回**
+
+连续伯努利分布的信息熵。
+
+
+kl_divergence(other)
+'''''''''
+
+相对于另一个连续伯努利分布的 KL 散度，两个分布需要有相同的 :math:`\text{batch shape}`。
+
+.. math::
+
+    KL\_divergence(\lambda_1, \lambda_2) = - H - \{\log C_2 + [\log \lambda_2 -  \log (1-\lambda_2)]  \mathbb{E}_1(X) +  \log (1-\lambda_2)  \}
+
+**参数**
+
+    - **other** (ContinuousBernoulli) - 输入的另一个连续伯努利分布。
+
+**返回**
+
+相对于另一个连续伯努利分布的 KL 散度。

docs/api/paddle/distribution/MultivariateNormal_cn.rst

@@ -0,0 +1,151 @@
+.. _cn_api_paddle_distribution_MultivariateNormal:
+
+MultivariateNormal
+-------------------------------
+
+.. py:class:: paddle.distribution.MultivariateNormal(loc, covariance_matrix=None, precision_matrix=None, scale_tril=None)
+
+
+MultivariateNormal 是一种定义在实数域上的多元连续型概率分布，参数 :attr:`loc` 表示均值，以及需要传入以下任意一种矩阵描述其方差：
+:attr:`covariance_matrix`、 :attr:`precision_matrix`、 :attr:`scale_tril`。
+
+其概率密度函数（pdf）为：
+
+.. math::
+
+    p(X ;\mu, \Sigma) = \frac{1}{\sqrt{(2\pi)^k |\Sigma|}} \exp(-\frac{1}{2}(X - \mu)^{\intercal} \Sigma^{-1} (X - \mu))
+
+其中：
+
+- :math:`X` 是 k 维随机向量。
+- :math:`\mu` 是 k 维均值向量。
+- :math:`\Sigma` 是 k 阶协方差矩阵。
+
+
+参数
+:::::::::
+
+    - **loc** (int|float|Tensor) - 即上述公式中 :math:`\mu` 参数，是 MultivariateNormal 的均值向量。如果 :attr:`loc` 的输入数据类型是 `int` 或 `float` 则会被转换为数据类型为 paddle 全局默认数据类型的 1-D Tensor。
+
+    - **covariance_matrix** (Tensor) - 即上述公式中 :math:`\mu` 参数，是 MultivariateNormal 的协方差矩阵。:attr:`covariance_matrix` 的数据类型会被转换为与 :attr:`loc` 相同的类型。默认值为 None。
+
+    - **precision_matrix** (Tensor) - 是 MultivariateNormal 协方差矩阵的逆矩阵。:attr:`precision_matrix` 的数据类型会被转换为与 :attr:`loc` 相同的类型。默认值为 None。
+
+    - **scale_tril** (Tensor) - 是 MultivariateNormal 协方差矩阵的柯列斯基分解的下三角矩阵。:attr:`scale_tril` 的数据类型会被转换为与 :attr:`loc` 相同的类型。默认值为 None。
+
+
+代码示例
+:::::::::
+
+COPY-FROM: paddle.distribution.MultivariateNormal
+
+属性
+:::::::::
+
+mean
+'''''''''
+
+MultivariateNormal 分布的均值
+
+**返回**
+
+Tensor，均值
+
+variance
+'''''''''
+
+MultivariateNormal 分布的方差
+
+**返回**
+
+Tensor，方差
+
+方法
+:::::::::
+
+prob(value)
+'''''''''
+
+计算 :attr:`value` 的概率。
+
+**参数**
+
+    - **value** (Tensor) - 待计算值。
+
+**返回**
+
+Tensor，:attr:`value` 的概率。数据类型与 `self.loc` 相同。
+
+
+log_prob(value)
+'''''''''
+
+计算 value 的对数概率。
+
+**参数**
+
+    - **value** (Tensor) - 待计算值。
+
+**返回**
+
+Tensor，:attr:`value` 的对数概率。数据类型与 `self.loc` 相同。
+
+
+sample(shape=())
+'''''''''
+
+从 MultivariateNormal 分布中生成满足特定形状的样本数据。最终生成样本形状为 ``sample_shape + batch_shape + event_shape`` 。
+
+**参数**
+
+    - **shape** (Sequence[int]，可选)：采样次数。
+
+**返回**
+
+Tensor，样本数据。其维度为 :math:`\text{sample shape} + \text{batch shape} + \text{event shape}` 。数据类型与 `self.loc` 相同。
+
+
+rsample(shape=())
+'''''''''
+
+重参数化采样，生成指定维度的样本。最终生成样本形状为 ``sample_shape + batch_shape + event_shape`` 。
+
+**参数**
+
+    - **shape** (Sequence[int]，可选)：采样次数。
+
+**返回**
+
+Tensor，样本数据。其维度为 :math:`\text{sample shape} + \text{batch shape} + \text{event shape}` 。数据类型与 `self.loc` 相同。
+
+
+entropy()
+'''''''''
+
+计算 MultivariateNormal 分布的信息熵。
+
+.. math::
+
+    \mathcal{H}(X) = \frac{n}{2} \log(2\pi) + \log {\det A} + \frac{n}{2}
+
+**返回**
+
+多元正态分布的信息熵，数据类型与 `self.loc` 相同。
+
+
+kl_divergence(other)
+'''''''''
+
+相对于另一个多元正态分布的 KL 散度，两个分布需要有相同的 :math:`\text{batch shape}` 和 :math:`\text{event shape}`。
+
+.. math::
+
+    KL\_divergence(\lambda_1, \lambda_2) = \log(\det A_2) - \log(\det A_1) -\frac{n}{2} +\frac{1}{2}[tr [\Sigma_2^{-1} \Sigma_1] + (\mu_1 - \mu_2)^{\intercal} \Sigma_2^{-1}  (\mu_1 - \mu_2)]
+
+**参数**
+
+    - **other** (MultivariateNormal) - 输入的另一个多元正态分布。
+
+**返回**
+
+相对于另一个多元正态分布的 KL 散度，数据类型与 `self.loc` 相同。

docs/api/paddle/distribution/Overview_cn.rst

@@ -23,12 +23,14 @@ 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:`ContinuousBernoulli <cn_api_paddle_distribution_ContinuousBernoulli>` ", "ContinuousBernoulli 概率分布类"
     " :ref:`Categorical <cn_api_paddle_distribution_Categorical>` ", "Categorical 概率分布类"
     " :ref:`Cauchy <cn_api_paddle_distribution_Cauchy>` ", "Cauchy 概率分布类"
     " :ref:`Normal <cn_api_paddle_distribution_Normal>` ", "Normal 概率分布类"
     " :ref:`Uniform <cn_api_paddle_distribution_Uniform>` ", "Uniform 概率分布类"
     " :ref:`Beta <cn_api_paddle_distribution_Beta>` ", "Beta 概率分布类"
     " :ref:`Dirichlet <cn_api_paddle_distribution_Dirichlet>` ", "Dirichlet 概率分布类"
+    " :ref:`MultivariateNormal <cn_api_paddle_distribution_MultivariateNormal>` ", "MultivariateNormal 概率分布类"
     " :ref:`Multinomial <cn_api_paddle_distribution_Multinomial>` ", "Multinomial 概率分布类"
     " :ref:`Independent <cn_api_paddle_distribution_Independent>` ", "Independent 概率分布类"
     " :ref:`TransfomedDistribution <cn_api_paddle_distribution_TransformedDistribution>` ", "TransformedDistribution 概率分布类"