Add Distribution, Uniform, Normal classes (#2417)

* test distribution doc

* add paddle.rst

* fix paddle.rst

* Add distribution_cn

* Fixed doc in cn

* fix cn doc

* test paddle_cn

* Distributin, temp fix of Normal and Uniform

* fix code doc

* test_broadcast

* optimize doc

* return to the original index_cn.rst

* hidden _to_variable func

doc/fluid/api/paddle.rst

@@ -41,6 +41,7 @@ paddle
 	paddle/diag.rst
 	paddle/disable_imperative.rst
 	paddle/dist.rst
+	paddle/distribution.rst
 	paddle/div.rst
 	paddle/dot.rst
 	paddle/elementwise_add.rst

doc/fluid/api/paddle/distribution.rst

+============
+distribution
+============
+
+..  toctree::
+    :maxdepth: 1
+
+    distribution/Distribution.rst
+    distribution/Normal.rst
+    distribution/Uniform.rst

doc/fluid/api/paddle/distribution/Distribution.rst

+..  THIS FILE IS GENERATED BY `gen_doc.{py|sh}`
+    !DO NOT EDIT THIS FILE MANUALLY!
+
+.. _api_distribution_Distribution:
+
+Distribution
+------------
+
+..  autoclass:: paddle.distribution.Distribution
+    :members:
+    :inherited-members:
+    :noindex:
+

doc/fluid/api/paddle/distribution/Normal.rst

+..  THIS FILE IS GENERATED BY `gen_doc.{py|sh}`
+    !DO NOT EDIT THIS FILE MANUALLY!
+
+.. _api_distribution_Normal:
+
+Normal
+------
+
+..  autoclass:: paddle.distribution.Normal
+    :members:
+    :inherited-members:
+    :noindex:
+

doc/fluid/api/paddle/distribution/Uniform.rst

+..  THIS FILE IS GENERATED BY `gen_doc.{py|sh}`
+    !DO NOT EDIT THIS FILE MANUALLY!
+
+.. _api_distribution_Uniform:
+
+Uniform
+-------
+
+..  autoclass:: paddle.distribution.Uniform
+    :members:
+    :inherited-members:
+    :noindex:
+

doc/fluid/api_cn/paddle_cn.rst

@@ -5,7 +5,7 @@ paddle
 ..  toctree::
 	:maxdepth: 1
 
-    paddle_cn/abs_cn.rst
+	paddle_cn/abs_cn.rst
 	paddle_cn/acos_cn.rst
 	paddle_cn/addcmul_cn.rst
 	paddle_cn/addmm_cn.rst
@@ -40,6 +40,7 @@ paddle
 	paddle_cn/diag_cn.rst
 	paddle_cn/disable_dygraph_cn.rst
 	paddle_cn/dist_cn.rst
+	paddle_cn/distribution_cn.rst
 	paddle_cn/dot_cn.rst
 	paddle_cn/elementwise_add_cn.rst
 	paddle_cn/elementwise_div_cn.rst
@@ -93,16 +94,16 @@ paddle
 	paddle_cn/log_cn.rst
 	paddle_cn/manual_seed_cn.rst
 	paddle_cn/matmul_cn.rst
-        paddle_cn/max_cn.rst
-        paddle_cn/maximum_cn.rst
+	paddle_cn/max_cn.rst
+	paddle_cn/maximum_cn.rst
 	paddle_cn/mean_cn.rst
 	paddle_cn/meshgrid_cn.rst
-        paddle_cn/min_cn.rst
-        paddle_cn/minimum_cn.rst
+	paddle_cn/min_cn.rst
+	paddle_cn/minimum_cn.rst
 	paddle_cn/multiplex_cn.rst
 	paddle_cn/mul_cn.rst
-    paddle_cn/name_scope_cn.rst
-    paddle_cn/no_grad_cn.rst
+	paddle_cn/name_scope_cn.rst
+	paddle_cn/no_grad_cn.rst
 	paddle_cn/nonzero_cn.rst
 	paddle_cn/not_equal_cn.rst
 	paddle_cn/numel_cn.rst

doc/fluid/api_cn/paddle_cn/distribution_cn.rst

+============
+distribution
+============
+
+..  toctree::
+    :maxdepth: 1
+
+    distribution_cn/Distribution_cn.rst
+    distribution_cn/Normal_cn.rst
+    distribution_cn/Uniform_cn.rst

doc/fluid/api_cn/paddle_cn/distribution_cn/Distribution_cn.rst

+.. _cn_api_distribution_Distribution:
+
+Distribution
+-------------------------------
+
+.. py:class:: paddle.distribution.Distribution()
+
+
+
+
+概率分布的抽象基类，在具体的分布中实现具体功能。
+
+
+.. py:function:: sample()
+
+从分布中采样
+
+.. py:function:: entropy()
+
+分布的信息熵
+
+.. py:function:: log_prob(value)
+
+对数概率密度函数
+
+参数：
+    - **value** (Tensor) - 输入张量。
+
+.. py:function:: probs(value)
+
+概率密度函数
+
+参数：
+    - **value** (Tensor) - 输入张量。
+
+.. py:function:: kl_divergence(other)
+
+两个分布之间的KL散度。
+
+参数：
+    - **other** (Distribution) - Distribution的实例。
+
+
+
+
+
+
+
+

doc/fluid/api_cn/paddle_cn/distribution_cn/Normal_cn.rst

+.. _cn_api_distribution_Normal:
+
+Normal
+-------------------------------
+
+.. py:class:: paddle.distribution.Normal(loc, scale, name=None)
+
+
+
+
+正态分布
+
+数学公式：
+
+.. math::
+
+    pdf(x; \mu, \sigma) = \frac{1}{Z}e^{\frac {-0.5 (x - \mu)^2}  {\sigma^2} }
+
+    Z = (2 \pi \sigma^2)^{0.5}
+
+上面的数学公式中：
+
+:math:`loc = \mu` : 平均值。
+:math:`scale = \sigma` : 标准差。
+:math:`Z`: 正态分布常量。
+
+参数：
+    - **loc** (int|float|list|numpy.ndarray|Tensor) - 正态分布平均值。数据类型为int、float32、list、numpy.ndarray或Tensor。
+    - **scale** (int|float|list|numpy.ndarray|Tensor) - 正态分布标准差。数据类型为int、float32、list、numpy.ndarray或Tensor。
+    - **name** (str，可选） - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。
+
+**代码示例**：
+
+.. code-block:: python
+
+    import numpy as np
+    import paddle
+    from paddle.distribution import Normal
+
+    paddle.disable_static()
+    # Define a single scalar Normal distribution.
+    dist = Normal(loc=0., scale=3.)
+    # Define a batch of two scalar valued Normals.
+    # The first has mean 1 and standard deviation 11, the second 2 and 22.
+    dist = Normal(loc=[1., 2.], scale=[11., 22.])
+    # Get 3 samples, returning a 3 x 2 tensor.
+    dist.sample([3])
+
+    # Define a batch of two scalar valued Normals.
+    # Both have mean 1, but different standard deviations.
+    dist = Normal(loc=1., scale=[11., 22.])
+
+    # Complete example
+    value_npdata = np.array([0.8], dtype="float32")
+    value_tensor = paddle.to_tensor(value_npdata)
+
+    normal_a = Normal([0.], [1.])
+    normal_b = Normal([0.5], [2.])
+    sample = normal_a.sample([2])
+    # a random tensor created by normal distribution with shape: [2, 1]
+    entropy = normal_a.entropy()
+    # [1.4189385] with shape: [1]
+    lp = normal_a.log_prob(value_tensor)
+    # [-1.2389386] with shape: [1]
+    p = normal_a.probs(value_tensor)
+    # [0.28969154] with shape: [1]
+    kl = normal_a.kl_divergence(normal_b)
+    # [0.34939718] with shape: [1]
+
+
+.. py:function:: sample(shape, seed=0)
+
+生成指定维度的样本
+
+参数：
+    - **shape** (list) - 1维列表，指定生成样本的维度。数据类型为int32。
+    - **seed** (int) - 长整型数。
+    
+返回：预先设计好维度的张量, 数据类型为float32
+
+返回类型：Tensor
+
+.. py:function:: entropy()
+
+信息熵
+    
+返回：正态分布的信息熵, 数据类型为float32
+
+返回类型：Tensor
+
+.. py:function:: log_prob(value)
+
+对数概率密度函数
+
+参数：
+    - **value** (Tensor) - 输入张量。数据类型为float32或float64。
+    
+返回：对数概率, 数据类型与value相同
+
+返回类型：Tensor
+
+.. py:function:: probs(value)
+
+概率密度函数
+
+参数：
+    - **value** (Tensor) - 输入张量。数据类型为float32或float64。
+    
+返回：概率, 数据类型与value相同
+
+返回类型：Tensor
+
+.. py:function:: kl_divergence(other)
+
+两个正态分布之间的KL散度。
+
+参数：
+    - **other** (Normal) - Normal的实例。
+    
+返回：两个正态分布之间的KL散度, 数据类型为float32
+
+返回类型：Tensor
+
+
+
+
+
+

doc/fluid/api_cn/paddle_cn/distribution_cn/Uniform_cn.rst

+.. _cn_api_distribution_Uniform:
+
+Uniform
+-------------------------------
+
+.. py:class:: paddle.distribution.Uniform(low, high, name=None)
+
+
+
+
+均匀分布
+
+概率密度函数（pdf）为：
+
+.. math::
+
+    pdf(x; a, b) = \frac{1}{Z},  a <=x < b
+
+    Z = b - a
+
+上面的数学公式中：
+
+:math:`low = a` 。
+:math:`high = b` 。
+:math:`Z`: 正态分布常量。
+
+参数low和high的维度必须能够支持广播。
+
+参数：
+    - **low** (int|float|list|numpy.ndarray|Tensor) - 均匀分布的下边界。数据类型为int、float32、list、numpy.ndarray或Tensor。
+    - **high** (int|float|list|numpy.ndarray|Tensor) - 均匀分布的上边界。数据类型为int、float32、list、numpy.ndarray或Tensor。
+    - **name** (str，可选） - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。
+
+**代码示例**：
+
+.. code-block:: python
+
+    import numpy as np
+    import paddle
+    from paddle.distribution import Uniform
+
+    paddle.disable_static()
+    # Without broadcasting, a single uniform distribution [3, 4]:
+    u1 = Uniform(low=3.0, high=4.0)
+    # 2 distributions [1, 3], [2, 4]
+    u2 = Uniform(low=[1.0, 2.0], high=[3.0, 4.0])
+    # 4 distributions
+    u3 = Uniform(low=[[1.0, 2.0], [3.0, 4.0]],
+            high=[[1.5, 2.5], [3.5, 4.5]])
+
+    # With broadcasting:
+    u4 = Uniform(low=3.0, high=[5.0, 6.0, 7.0])
+
+    # Complete example
+    value_npdata = np.array([0.8], dtype="float32")
+    value_tensor = paddle.to_tensor(value_npdata)
+
+    uniform = Uniform([0.], [2.])
+
+    sample = uniform.sample([2])
+    # a random tensor created by uniform distribution with shape: [2, 1]
+    entropy = uniform.entropy()
+    # [0.6931472] with shape: [1]
+    lp = uniform.log_prob(value_tensor)
+    # [-0.6931472] with shape: [1]
+    p = uniform.probs(value_tensor)
+    # [0.5] with shape: [1]
+
+
+.. py:function:: sample(shape, seed=0)
+
+生成指定维度的样本
+
+参数：
+    - **shape** (list) - 1维列表，指定生成样本的维度。数据类型为int32。
+    - **seed** (int) - 长整型数。
+    
+返回：预先设计好维度的张量, 数据类型为float32
+
+返回类型：Tensor
+
+.. py:function:: entropy()
+
+信息熵
+    
+返回：均匀分布的信息熵, 数据类型为float32
+
+返回类型：Tensor
+
+.. py:function:: log_prob(value)
+
+对数概率密度函数
+
+参数：
+    - **value** (Tensor) - 输入张量。数据类型为float32或float64。
+    
+返回：对数概率, 数据类型与value相同
+
+返回类型：Tensor
+
+.. py:function:: probs(value)
+
+概率密度函数
+
+参数：
+    - **value** (Tensor) - 输入张量。数据类型为float32或float64。
+    
+返回：概率, 数据类型与value相同
+
+返回类型：Tensor
+
+
+
+
+