From 9e09cea68e598b9d74e556f5d0de3672eeb31247 Mon Sep 17 00:00:00 2001 From: zhupengyang Date: Wed, 2 Sep 2020 20:28:53 +0800 Subject: [PATCH] refind rand, randn, standard_normal, normal, randint, randperm docs (#2528) * refind rand, randn, standard_normal, normal, randint, randperm docs test=develop * test=develop --- .../api/paddle/tensor/random/normal_cn.rst | 48 ++++++++++++++++++ .../api/paddle/tensor/random/rand_cn.rst | 44 +++++++--------- .../api/paddle/tensor/random/randint_cn.rst | 46 +++++++---------- .../api/paddle/tensor/random/randn_cn.rst | 44 +++++++--------- .../api/paddle/tensor/random/randperm_cn.rst | 20 +++----- .../tensor/random/standard_normal_cn.rst | 50 +++++++++++++++++++ 6 files changed, 155 insertions(+), 97 deletions(-) create mode 100644 doc/paddle/api/paddle/tensor/random/normal_cn.rst create mode 100644 doc/paddle/api/paddle/tensor/random/standard_normal_cn.rst diff --git a/doc/paddle/api/paddle/tensor/random/normal_cn.rst b/doc/paddle/api/paddle/tensor/random/normal_cn.rst new file mode 100644 index 000000000..ac57976ad --- /dev/null +++ b/doc/paddle/api/paddle/tensor/random/normal_cn.rst @@ -0,0 +1,48 @@ +.. _cn_api_tensor_random_normal: + +normal +------------------------------- + +.. py:function:: paddle.normal(mean=0.0, std=1.0, shape=None, name=None) + + +该OP返回符合正态分布（均值为 ``mean`` ，标准差为 ``std`` 的正态随机分布）的随机Tensor。 + +如果 ``mean`` 是Tensor，则输出Tensor和 ``mean`` 具有相同的形状和数据类型。 +如果 ``mean`` 不是Tensor，且 ``std`` 是Tensor，则输出Tensor和 ``std`` 具有相同的形状和数据类型。 +如果 ``mean`` 和 ``std`` 都不是Tensor，则输出Tensor的形状为 ``shape``，数据类型为float32。 + +如果 ``mean`` 和 ``std`` 都是Tensor，则 ``mean`` 和 ``std`` 的元素个数应该相同。 + +参数 +:::::::::: + - mean (float|Tensor, 可选) - 输出Tensor的正态分布的平均值。如果 ``mean`` 是float，则表示输出Tensor中所有元素的正态分布的平均值。如果 ``mean`` 是Tensor(支持的数据类型为float32、float64)，则表示输出Tensor中每个元素的正态分布的平均值。默认值为0.0 + - std (float|Tensor, 可选) - 输出Tensor的正态分布的标准差。如果 ``std`` 是float，则表示输出Tensor中所有元素的正态分布的标准差。如果 ``std`` 是Tensor(支持的数据类型为float32、float64)，则表示输出Tensor中每个元素的正态分布的标准差。默认值为0.0 + - shape (list|tuple|Tensor, 可选) - 生成的随机Tensor的形状。如果 ``shape`` 是list、tuple，则其中的元素可以是int，或者是形状为[1]且数据类型为int32、int64的Tensor。如果 ``shape`` 是Tensor，则是数据类型为int32、int64的1-D Tensor。如果 ``mean`` 或者 ``std`` 是Tensor，输出Tensor的形状和 ``mean`` 或者 ``std`` 相同(此时 ``shape`` 无效)。默认值为None。 + - name (str, 可选) - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + +返回 +:::::::::: + Tensor：符合正态分布（均值为 ``mean`` ，标准差为 ``std`` 的正态随机分布）的随机Tensor。 + +示例代码 +:::::::::: + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + + out1 = paddle.normal(shape=[2, 3]) + # [[ 0.17501129 0.32364586 1.561118 ] # random + # [-1.7232178 1.1545963 -0.76156676]] # random + + mean_tensor = paddle.to_tensor(np.array([1.0, 2.0, 3.0])) + out2 = paddle.normal(mean=mean_tensor) + # [ 0.18644847 -1.19434458 3.93694787] # random + + std_tensor = paddle.to_tensor(np.array([1.0, 2.0, 3.0])) + out3 = paddle.normal(mean=mean_tensor, std=std_tensor) + # [1.00780561 3.78457445 5.81058198] # random diff --git a/doc/paddle/api/paddle/tensor/random/rand_cn.rst b/doc/paddle/api/paddle/tensor/random/rand_cn.rst index 36fc3f1a6..5045d6d4f 100644 --- a/doc/paddle/api/paddle/tensor/random/rand_cn.rst +++ b/doc/paddle/api/paddle/tensor/random/rand_cn.rst @@ -5,11 +5,6 @@ rand .. py:function:: paddle.rand(shape, dtype=None, name=None) -:alias_main: paddle.rand -:alias: paddle.tensor.rand, paddle.tensor.random.rand - - - 该OP返回符合均匀分布的，范围在[0, 1)的Tensor，形状为 ``shape``，数据类型为 ``dtype``。 参数 @@ -22,11 +17,6 @@ rand :::::::::: Tensor: 符合均匀分布的范围为[0, 1)的随机Tensor，形状为 ``shape``，数据类型为 ``dtype``。 -抛出异常 -:::::::::: - - ``TypeError`` - 如果 ``shape`` 的类型不是list、tuple、Tensor。 - - ``TypeError`` - 如果 ``dtype`` 不是float32、float64。 - 示例代码 :::::::::: @@ -35,25 +25,25 @@ rand import paddle import numpy as np - paddle.enable_imperative() + paddle.disable_static() # example 1: attr shape is a list which doesn't contain Tensor. - result_1 = paddle.rand(shape=[2, 3]) - # [[0.451152 , 0.55825245, 0.403311 ], - # [0.22550228, 0.22106001, 0.7877319 ]] + out1 = paddle.rand(shape=[2, 3]) + # [[0.451152 , 0.55825245, 0.403311 ], # random + # [0.22550228, 0.22106001, 0.7877319 ]] # random # example 2: attr shape is a list which contains Tensor. - dim_1 = paddle.fill_constant([1], "int64", 2) - dim_2 = paddle.fill_constant([1], "int32", 3) - result_2 = paddle.rand(shape=[dim_1, dim_2, 2]) - # [[[0.8879919 0.25788337] - # [0.28826773 0.9712097 ] - # [0.26438272 0.01796806]] - # [[0.33633623 0.28654453] - # [0.79109055 0.7305809 ] - # [0.870881 0.2984597 ]]] + dim1 = paddle.full([1], 2, "int64") + dim2 = paddle.full([1], 3, "int32") + out2 = paddle.rand(shape=[dim1, dim2, 2]) + # [[[0.8879919 , 0.25788337], # random + # [0.28826773, 0.9712097 ], # random + # [0.26438272, 0.01796806]], # random + # [[0.33633623, 0.28654453], # random + # [0.79109055, 0.7305809 ], # random + # [0.870881 , 0.2984597 ]]] # random # example 3: attr shape is a Tensor, the data type must be int64 or int32. - var_shape = paddle.imperative.to_variable(np.array([2, 3])) - result_3 = paddle.rand(var_shape) - # [[0.22920267 0.841956 0.05981819] - # [0.4836288 0.24573246 0.7516129 ]] + shape_tensor = paddle.to_tensor(np.array([2, 3])) + out2 = paddle.rand(shape_tensor) + # [[0.22920267, 0.841956 , 0.05981819], # random + # [0.4836288 , 0.24573246, 0.7516129 ]] # random diff --git a/doc/paddle/api/paddle/tensor/random/randint_cn.rst b/doc/paddle/api/paddle/tensor/random/randint_cn.rst index e2ef78ff5..bac8502dc 100644 --- a/doc/paddle/api/paddle/tensor/random/randint_cn.rst +++ b/doc/paddle/api/paddle/tensor/random/randint_cn.rst @@ -1,15 +1,10 @@ -.. _cn_api_tensor_randint: +.. _cn_api_tensor_random_randint: randint ------------------------------- .. py:function:: paddle.randint(low=0, high=None, shape=[1], dtype=None, name=None) -:alias_main: paddle.randint -:alias: paddle.tensor.randint, paddle.tensor.random.randint - - - 该OP返回服从均匀分布的、范围在[``low``, ``high``)的随机Tensor，形状为 ``shape``，数据类型为 ``dtype``。当 ``high`` 为None时（默认），均匀采样的区间为[0, ``low``)。 参数 @@ -24,12 +19,6 @@ randint :::::::::: Tensor：从区间[``low``，``high``)内均匀分布采样的随机Tensor，形状为 ``shape``，数据类型为 ``dtype``。 -抛出异常 -:::::::::: - - ``TypeError`` - 如果 ``shape`` 的类型不是list、tuple、Tensor。 - - ``TypeError`` - 如果 ``dtype`` 不是int32、int64。 - - ``ValueError`` - 如果 ``high`` 不大于 ``low``；或者 ``high`` 为None，且 ``low`` 不大于0。 - 代码示例 ::::::::::: @@ -38,35 +27,34 @@ randint import paddle import numpy as np - paddle.enable_imperative() + paddle.disable_static() # example 1: # attr shape is a list which doesn't contain Tensor. - result_1 = paddle.randint(low=-5, high=5, shape=[3]) - # [0, -3, 2] + out1 = paddle.randint(low=-5, high=5, shape=[3]) + # [0, -3, 2] # random # example 2: # attr shape is a list which contains Tensor. - dim_1 = paddle.fill_constant([1], "int64", 2) - dim_2 = paddle.fill_constant([1], "int32", 3) - result_2 = paddle.randint(low=-5, high=5, shape=[dim_1, dim_2], dtype="int32") - print(result_2.numpy()) - # [[ 0, -1, -3], - # [ 4, -2, 0]] + dim1 = paddle.full([1], 2, "int64") + dim2 = paddle.full([1], 3, "int32") + out2 = paddle.randint(low=-5, high=5, shape=[dim1, dim2], dtype="int32") + # [[0, -1, -3], # random + # [4, -2, 0]] # random # example 3: # attr shape is a Tensor - var_shape = paddle.imperative.to_variable(np.array([3])) - result_3 = paddle.randint(low=-5, high=5, shape=var_shape) - # [-2, 2, 3] + shape_tensor = paddle.to_tensor(np.array([3])) + out3 = paddle.randint(low=-5, high=5, shape=shape_tensor) + # [-2, 2, 3] # random # example 4: - # date type is int32 - result_4 = paddle.randint(low=-5, high=5, shape=[3], dtype='int32') - # [-5, 4, -4] + # data type is int32 + out4 = paddle.randint(low=-5, high=5, shape=[3], dtype='int32') + # [-5, 4, -4] # random # example 5: # Input only one parameter # low=0, high=10, shape=[1], dtype='int64' - result_5 = paddle.randint(10) - # [7] + out5 = paddle.randint(10) + # [7] # random diff --git a/doc/paddle/api/paddle/tensor/random/randn_cn.rst b/doc/paddle/api/paddle/tensor/random/randn_cn.rst index e465b0c75..fa9b18fb9 100644 --- a/doc/paddle/api/paddle/tensor/random/randn_cn.rst +++ b/doc/paddle/api/paddle/tensor/random/randn_cn.rst @@ -5,11 +5,6 @@ randn .. py:function:: paddle.randn(shape, dtype=None, name=None) -:alias_main: paddle.randn -:alias: paddle.tensor.randn, paddle.tensor.random.randn - - - 该OP返回符合标准正态分布（均值为0，标准差为1的正态随机分布）的随机Tensor，形状为 ``shape``，数据类型为 ``dtype``。 参数 @@ -22,11 +17,6 @@ randn :::::::::: Tensor：符合标准正态分布的随机Tensor，形状为 ``shape``，数据类型为 ``dtype``。 -抛出异常 -:::::::::: - - ``TypeError`` - 如果 ``shape`` 的类型不是list、tuple、Tensor。 - - ``TypeError`` - 如果 ``dtype`` 不是float32、float64。 - 示例代码 :::::::::: @@ -35,26 +25,26 @@ randn import paddle import numpy as np - paddle.enable_imperative() + paddle.disable_static() # example 1: attr shape is a list which doesn't contain Tensor. - result_1 = paddle.randn(shape=[2, 3]) - # [[-2.923464 0.11934398 -0.51249987] - # [ 0.39632758 0.08177969 0.2692008 ]] + out1 = paddle.randn(shape=[2, 3]) + # [[-2.923464 , 0.11934398, -0.51249987], # random + # [ 0.39632758, 0.08177969, 0.2692008 ]] # random # example 2: attr shape is a list which contains Tensor. - dim_1 = paddle.fill_constant([1], "int64", 2) - dim_2 = paddle.fill_constant([1], "int32", 3) - result_2 = paddle.randn(shape=[dim_1, dim_2, 2]) - # [[[-2.8852394 -0.25898588] - # [-0.47420555 0.17683524] - # [-0.7989969 0.00754541]] - # [[ 0.85201347 0.32320443] - # [ 1.1399018 0.48336947] - # [ 0.8086993 0.6868893 ]]] + dim1 = paddle.full([1], 2, "int64") + dim2 = paddle.full([1], 3, "int32") + out2 = paddle.randn(shape=[dim1, dim2, 2]) + # [[[-2.8852394 , -0.25898588], # random + # [-0.47420555, 0.17683524], # random + # [-0.7989969 , 0.00754541]], # random + # [[ 0.85201347, 0.32320443], # random + # [ 1.1399018 , 0.48336947], # random + # [ 0.8086993 , 0.6868893 ]]] # random # example 3: attr shape is a Tensor, the data type must be int64 or int32. - var_shape = paddle.imperative.to_variable(np.array([2, 3])) - result_3 = paddle.randn(var_shape) - # [[-2.878077 0.17099959 0.05111201] - # [-0.3761474 -1.044801 1.1870178 ]] + shape_tensor = paddle.to_tensor(np.array([2, 3])) + out3 = paddle.randn(shape_tensor) + # [[-2.878077 , 0.17099959, 0.05111201] # random + # [-0.3761474, -1.044801 , 1.1870178 ]] # random diff --git a/doc/paddle/api/paddle/tensor/random/randperm_cn.rst b/doc/paddle/api/paddle/tensor/random/randperm_cn.rst index d3c756a0f..c78212af8 100644 --- a/doc/paddle/api/paddle/tensor/random/randperm_cn.rst +++ b/doc/paddle/api/paddle/tensor/random/randperm_cn.rst @@ -5,9 +5,6 @@ randperm .. py:function:: paddle.randperm(n, dtype="int64", name=None) -:alias_main: paddle.randperm -:alias: paddle.tensor.randperm, paddle.tensor.random.randperm - 该OP返回一个数值在0到n-1、随机排列的1-D Tensor，数据类型为 ``dtype``。 参数: @@ -20,22 +17,17 @@ randperm :::::::::: Tensor：一个数值在0到n-1、随机排列的1-D Tensor，数据类型为 ``dtype`` 。 -抛出异常 -:::::::::: - - ValueError - 如果 ``n`` 不大于0. - - TypeError - 如果 ``dtype`` 不是int32、int64、float32、float64. - 代码示例 :::::::::: -.. code-block:: python +.. code-block:: python import paddle - paddle.enable_imperative() + paddle.disable_static() - result_1 = paddle.randperm(5) - # [4 1 2 3 0] + out1 = paddle.randperm(5) + # [4, 1, 2, 3, 0] # random - result_2 = paddle.randperm(7, 'int32') - # [1 6 2 0 4 3 5] + out2 = paddle.randperm(7, 'int32') + # [1, 6, 2, 0, 4, 3, 5] # random diff --git a/doc/paddle/api/paddle/tensor/random/standard_normal_cn.rst b/doc/paddle/api/paddle/tensor/random/standard_normal_cn.rst new file mode 100644 index 000000000..d379107d6 --- /dev/null +++ b/doc/paddle/api/paddle/tensor/random/standard_normal_cn.rst @@ -0,0 +1,50 @@ +.. _cn_api_tensor_random_standard_normal: + +standard_normal +------------------------------- + +.. py:function:: paddle.standard_normal(shape, dtype=None, name=None) + +该OP返回符合标准正态分布（均值为0，标准差为1的正态随机分布）的随机Tensor，形状为 ``shape``，数据类型为 ``dtype``。 + +参数 +:::::::::: + - **shape** (list|tuple|Tensor) - 生成的随机Tensor的形状。如果 ``shape`` 是list、tuple，则其中的元素可以是int，或者是形状为[1]且数据类型为int32、int64的Tensor。如果 ``shape`` 是Tensor，则是数据类型为int32、int64的1-D Tensor。 + - **dtype** (str|np.dtype|core.VarDesc.VarType, 可选) - 输出Tensor的数据类型，支持float32、float64。当该参数值为None时， 输出Tensor的数据类型为float32。默认值为None. + - **name** (str, 可选) - 输出的名字。一般无需设置，默认值为None。该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` 。 + +返回 +:::::::::: + Tensor：符合标准正态分布的随机Tensor，形状为 ``shape``，数据类型为 ``dtype``。 + +示例代码 +:::::::::: + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + + # example 1: attr shape is a list which doesn't contain Tensor. + out1 = paddle.standard_normal(shape=[2, 3]) + # [[-2.923464 , 0.11934398, -0.51249987], # random + # [ 0.39632758, 0.08177969, 0.2692008 ]] # random + + # example 2: attr shape is a list which contains Tensor. + dim1 = paddle.full([1], 2, "int64") + dim2 = paddle.full([1], 3, "int32") + out2 = paddle.standard_normal(shape=[dim1, dim2, 2]) + # [[[-2.8852394 , -0.25898588], # random + # [-0.47420555, 0.17683524], # random + # [-0.7989969 , 0.00754541]], # random + # [[ 0.85201347, 0.32320443], # random + # [ 1.1399018 , 0.48336947], # random + # [ 0.8086993 , 0.6868893 ]]] # random + + # example 3: attr shape is a Tensor, the data type must be int64 or int32. + shape_tensor = paddle.to_tensor(np.array([2, 3])) + out3 = paddle.standard_normal(shape_tensor) + # [[-2.878077 , 0.17099959, 0.05111201] # random + # [-0.3761474, -1.044801 , 1.1870178 ]] # random -- GitLab