From 08e429cb552587d840df049279ac921108638cf5 Mon Sep 17 00:00:00 2001 From: pangyoki Date: Sat, 22 Aug 2020 03:47:28 -0500 Subject: [PATCH] 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 | 1 + doc/fluid/api/paddle/distribution.rst | 10 ++ .../api/paddle/distribution/Distribution.rst | 13 ++ doc/fluid/api/paddle/distribution/Normal.rst | 13 ++ doc/fluid/api/paddle/distribution/Uniform.rst | 13 ++ doc/fluid/api_cn/paddle_cn.rst | 15 +- .../api_cn/paddle_cn/distribution_cn.rst | 10 ++ .../distribution_cn/Distribution_cn.rst | 49 +++++++ .../paddle_cn/distribution_cn/Normal_cn.rst | 128 ++++++++++++++++++ .../paddle_cn/distribution_cn/Uniform_cn.rst | 115 ++++++++++++++++ 10 files changed, 360 insertions(+), 7 deletions(-) create mode 100644 doc/fluid/api/paddle/distribution.rst create mode 100644 doc/fluid/api/paddle/distribution/Distribution.rst create mode 100644 doc/fluid/api/paddle/distribution/Normal.rst create mode 100644 doc/fluid/api/paddle/distribution/Uniform.rst create mode 100644 doc/fluid/api_cn/paddle_cn/distribution_cn.rst create mode 100644 doc/fluid/api_cn/paddle_cn/distribution_cn/Distribution_cn.rst create mode 100644 doc/fluid/api_cn/paddle_cn/distribution_cn/Normal_cn.rst create mode 100644 doc/fluid/api_cn/paddle_cn/distribution_cn/Uniform_cn.rst diff --git a/doc/fluid/api/paddle.rst b/doc/fluid/api/paddle.rst index ca0402d65..371c0e958 100644 --- a/doc/fluid/api/paddle.rst +++ b/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 diff --git a/doc/fluid/api/paddle/distribution.rst b/doc/fluid/api/paddle/distribution.rst new file mode 100644 index 000000000..76ee9f2ee --- /dev/null +++ b/doc/fluid/api/paddle/distribution.rst @@ -0,0 +1,10 @@ +============ +distribution +============ + +.. toctree:: + :maxdepth: 1 + + distribution/Distribution.rst + distribution/Normal.rst + distribution/Uniform.rst diff --git a/doc/fluid/api/paddle/distribution/Distribution.rst b/doc/fluid/api/paddle/distribution/Distribution.rst new file mode 100644 index 000000000..dbfe5082f --- /dev/null +++ b/doc/fluid/api/paddle/distribution/Distribution.rst @@ -0,0 +1,13 @@ +.. 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: + diff --git a/doc/fluid/api/paddle/distribution/Normal.rst b/doc/fluid/api/paddle/distribution/Normal.rst new file mode 100644 index 000000000..f0f972fd7 --- /dev/null +++ b/doc/fluid/api/paddle/distribution/Normal.rst @@ -0,0 +1,13 @@ +.. 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: + diff --git a/doc/fluid/api/paddle/distribution/Uniform.rst b/doc/fluid/api/paddle/distribution/Uniform.rst new file mode 100644 index 000000000..81b5d8dcd --- /dev/null +++ b/doc/fluid/api/paddle/distribution/Uniform.rst @@ -0,0 +1,13 @@ +.. 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: + diff --git a/doc/fluid/api_cn/paddle_cn.rst b/doc/fluid/api_cn/paddle_cn.rst index c5cc57f3e..7a3721511 100644 --- a/doc/fluid/api_cn/paddle_cn.rst +++ b/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 diff --git a/doc/fluid/api_cn/paddle_cn/distribution_cn.rst b/doc/fluid/api_cn/paddle_cn/distribution_cn.rst new file mode 100644 index 000000000..acbdd00b7 --- /dev/null +++ b/doc/fluid/api_cn/paddle_cn/distribution_cn.rst @@ -0,0 +1,10 @@ +============ +distribution +============ + +.. toctree:: + :maxdepth: 1 + + distribution_cn/Distribution_cn.rst + distribution_cn/Normal_cn.rst + distribution_cn/Uniform_cn.rst diff --git a/doc/fluid/api_cn/paddle_cn/distribution_cn/Distribution_cn.rst b/doc/fluid/api_cn/paddle_cn/distribution_cn/Distribution_cn.rst new file mode 100644 index 000000000..c513c281d --- /dev/null +++ b/doc/fluid/api_cn/paddle_cn/distribution_cn/Distribution_cn.rst @@ -0,0 +1,49 @@ +.. _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的实例。 + + + + + + + + diff --git a/doc/fluid/api_cn/paddle_cn/distribution_cn/Normal_cn.rst b/doc/fluid/api_cn/paddle_cn/distribution_cn/Normal_cn.rst new file mode 100644 index 000000000..c1bc0c8b5 --- /dev/null +++ b/doc/fluid/api_cn/paddle_cn/distribution_cn/Normal_cn.rst @@ -0,0 +1,128 @@ +.. _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 + + + + + + diff --git a/doc/fluid/api_cn/paddle_cn/distribution_cn/Uniform_cn.rst b/doc/fluid/api_cn/paddle_cn/distribution_cn/Uniform_cn.rst new file mode 100644 index 000000000..382d1e9c6 --- /dev/null +++ b/doc/fluid/api_cn/paddle_cn/distribution_cn/Uniform_cn.rst @@ -0,0 +1,115 @@ +.. _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 + + + + + -- GitLab