From 0ca1bb56dfac37c569cfafbf883eb2be3a40ad9d Mon Sep 17 00:00:00 2001 From: zhupengyang Date: Wed, 29 Jul 2020 15:06:04 +0800 Subject: [PATCH] refine docs of rand, randn, randint, randperm, zeros_like, arange (#25633) --- python/paddle/fluid/layers/nn.py | 119 ++++++---- python/paddle/fluid/layers/tensor.py | 53 +++-- .../unittests/test_gaussian_random_op.py | 15 +- .../fluid/tests/unittests/test_ones_op.py | 4 +- .../tests/unittests/test_uniform_random_op.py | 6 + python/paddle/tensor/creation.py | 87 +++---- python/paddle/tensor/random.py | 218 +++++++++--------- 7 files changed, 276 insertions(+), 226 deletions(-) diff --git a/python/paddle/fluid/layers/nn.py b/python/paddle/fluid/layers/nn.py index a894dbd005..cde57c9fef 100644 --- a/python/paddle/fluid/layers/nn.py +++ b/python/paddle/fluid/layers/nn.py @@ -10427,47 +10427,58 @@ def gaussian_random(shape, dtype='float32', name=None): """ - Generate a random tensor whose data is drawn from a Gaussian distribution. + This OP returns a Tensor filled with random values sampled from a Gaussian + distribution, with ``shape`` and ``dtype``. Args: - shape(list|tuple|Variable): Shape of the Tensor to be created. The data - type is ``int32`` or ``int64`` . If ``shape`` is a list or tuple, - the elements of it should be integers or Tensors with shape [1]. If - ``shape`` is a Variable, it should be an 1-D Tensor . - mean(float): Mean of the random tensor, defaults to 0.0. - std(float): Standard deviation of the random tensor, defaults to 1.0. - seed(int): ${seed_comment} - dtype(np.dtype|core.VarDesc.VarType|str, optional): Data type of the output - tensor, which can be float32, float64. Default is float32. - name(str, optional): Normally there is no need for user to set this property. - For more information, please refer to :ref:`api_guide_Name` . - Default is None. + shape(list|tuple|Tensor): The shape of the output Tensor. If ``shape`` + is a list or tuple, the elements of it should be integers or Tensors + (with the shape [1], and the data type int32 or int64). If ``shape`` + is a Tensor, it should be a 1-D Tensor(with the data type int32 or + int64). + mean(float|int, optional): Mean of the output tensor, default is 0.0. + std(float|int, optional): Standard deviation of the output tensor, default + is 1.0. + seed(int, optional): ${seed_comment} + dtype(str|np.dtype|core.VarDesc.VarType, optional): The data type of + the output Tensor. Supported data types: float32, float64. + Default is float32. + name(str, optional): The default value is None. Normally there is no + need for user to set this property. For more information, please + refer to :ref:`api_guide_Name`. Returns: - Variable: Random tensor whose data is drawn from a Gaussian distribution, dtype: flaot32 or float64 as specified. + Tensor: A Tensor filled with random values sampled from a Gaussian + distribution, with ``shape`` and ``dtype``. Examples: - .. code-block:: python import paddle.fluid as fluid # example 1: - # attr shape is a list which doesn't contain tensor Variable. + # attr shape is a list which doesn't contain Tensor. result_1 = fluid.layers.gaussian_random(shape=[3, 4]) + # [[-0.31261674, 1.8736548, -0.6274357, 0.96988016], + # [-0.12294637, 0.9554768, 1.5690808, -1.2894802 ], + # [-0.60082096, -0.61138713, 1.5345167, -0.21834975]] # example 2: - # attr shape is a list which contains tensor Variable. - dim_1 = fluid.layers.fill_constant([1],"int64",3) - dim_2 = fluid.layers.fill_constant([1],"int32",5) + # attr shape is a list which contains Tensor. + dim_1 = fluid.layers.fill_constant([1], "int64", 2) + dim_2 = fluid.layers.fill_constant([1], "int32", 3) result_2 = fluid.layers.gaussian_random(shape=[dim_1, dim_2]) + # [[ 0.51398206, -0.3389769, 0.23597084], + # [ 1.0388143, -1.2015356, -1.0499583 ]] # example 3: - # attr shape is a Variable, the data type must be int64 or int32. + # attr shape is a Tensor, the data type must be int64 or int32. var_shape = fluid.data(name='var_shape', shape=[2], dtype="int64") result_3 = fluid.layers.gaussian_random(var_shape) - var_shape_int32 = fluid.data(name='var_shape_int32', shape=[2], dtype="int32") - result_4 = fluid.layers.gaussian_random(var_shape_int32) + # if var_shape's value is [2, 3] + # result_3 is: + # [[-0.12310527, 0.8187662, 1.923219 ] + # [ 0.70721835, 0.5210541, -0.03214082]] .. code-block:: python @@ -10509,8 +10520,10 @@ def gaussian_random(shape, if in_dygraph_mode(): shape = utils._convert_shape_to_list(shape) - return core.ops.gaussian_random('shape', shape, 'mean', mean, 'std', - std, 'seed', seed, 'dtype', dtype) + return core.ops.gaussian_random('shape', shape, 'mean', + float(mean), 'std', + float(std), 'seed', seed, 'dtype', + dtype) check_type(shape, 'shape', (list, tuple, Variable), 'gaussian_random/randn') check_dtype(dtype, 'dtype', ['float32', 'float64'], 'gaussian_random/randn') @@ -14917,8 +14930,8 @@ def gather_tree(ids, parents): def uniform_random(shape, dtype='float32', min=-1.0, max=1.0, seed=0, name=None): """ - This OP initializes a variable with random values sampled from a - uniform distribution in the range [min, max). + This OP returns a Tensor filled with random values sampled from a uniform + distribution in the range [``min``, ``max``), with ``shape`` and ``dtype``. Examples: :: @@ -14930,30 +14943,33 @@ def uniform_random(shape, dtype='float32', min=-1.0, max=1.0, seed=0, result=[[0.8505902, 0.8397286]] Args: - shape (list|tuple|Variable): The shape of the output Tensor, if the - shape is a list or tuple, its elements can be an integer or a - Tensor with the shape [1], and the type of the Tensor must be - int32 or int64. If the shape is a Variable, it is a 1-D Tensor, and - the type of the Tensor must be int32 or int64. - dtype(np.dtype|core.VarDesc.VarType|str, optional): The type of the - output Tensor. Supported data types: float32, float64. Default: float32. - min (float, optional): The lower bound on the range of random values - to generate, the min is included in the range. Default -1.0. - max (float, optional): The upper bound on the range of random values - to generate, the max is excluded in the range. Default 1.0. - seed (int, optional): Random seed used for generating samples. 0 means + shape(list|tuple|Tensor): The shape of the output Tensor. If ``shape`` + is a list or tuple, the elements of it should be integers or Tensors + (with the shape [1], and the data type int32 or int64). If ``shape`` + is a Tensor, it should be a 1-D Tensor(with the data type int32 or + int64). + dtype(str|np.dtype|core.VarDesc.VarType, optional): The data type of + the output Tensor. Supported data types: float32, float64. + Default is float32. + min(float|int, optional): The lower bound on the range of random values + to generate, ``min`` is included in the range. Default is -1.0. + max(float|int, optional): The upper bound on the range of random values + to generate, ``max`` is excluded in the range. Default is 1.0. + seed(int, optional): Random seed used for generating samples. 0 means use a seed generated by the system. Note that if seed is not 0, this operator will always generate the same random numbers every - time. Default 0. + time. Default is 0. name(str, optional): The default value is None. Normally there is no need for user to set this property. For more information, please refer to :ref:`api_guide_Name`. Returns: - Variable: A Tensor of the specified shape filled with uniform_random values. + Tensor: A Tensor filled with random values sampled from a uniform + distribution in the range [``min``, ``max``), with ``shape`` and ``dtype``. Raises: - TypeError: The shape type should be list or tuple or variable. + TypeError: If ``shape`` is not list, tuple, Tensor. + TypeError: If ``dtype`` is not float32, float64. Examples: .. code-block:: python @@ -14961,21 +14977,28 @@ def uniform_random(shape, dtype='float32', min=-1.0, max=1.0, seed=0, import paddle.fluid as fluid # example 1: - # attr shape is a list which doesn't contain tensor Variable. + # attr shape is a list which doesn't contain Tensor. result_1 = fluid.layers.uniform_random(shape=[3, 4]) + # [[ 0.84524226, 0.6921872, 0.56528175, 0.71690357], + # [-0.34646994, -0.45116323, -0.09902662, -0.11397249], + # [ 0.433519, 0.39483607, -0.8660099, 0.83664286]] # example 2: - # attr shape is a list which contains tensor Variable. - dim_1 = fluid.layers.fill_constant([1],"int64",3) - dim_2 = fluid.layers.fill_constant([1],"int32",5) + # attr shape is a list which contains Tensor. + dim_1 = fluid.layers.fill_constant([1], "int64", 2) + dim_2 = fluid.layers.fill_constant([1], "int32", 3) result_2 = fluid.layers.uniform_random(shape=[dim_1, dim_2]) + # [[-0.9951253, 0.30757582, 0.9899647 ], + # [ 0.5864527, 0.6607096, -0.8886161 ]] # example 3: - # attr shape is a Variable, the data type must be int64 or int32. + # attr shape is a Tensor, the data type must be int64 or int32. var_shape = fluid.data(name='var_shape', shape=[2], dtype="int64") result_3 = fluid.layers.uniform_random(var_shape) - var_shape_int32 = fluid.data(name='var_shape_int32', shape=[2], dtype="int32") - result_4 = fluid.layers.uniform_random(var_shape_int32) + # if var_shape's value is [2, 3] + # result_3 is: + # [[-0.8517412, -0.4006908, 0.2551912 ], + # [ 0.3364414, 0.36278176, -0.16085452]] """ if not isinstance(dtype, core.VarDesc.VarType): diff --git a/python/paddle/fluid/layers/tensor.py b/python/paddle/fluid/layers/tensor.py index f31c6a9db8..54867e727e 100644 --- a/python/paddle/fluid/layers/tensor.py +++ b/python/paddle/fluid/layers/tensor.py @@ -1335,35 +1335,38 @@ def isfinite(x): def range(start, end, step, dtype, name=None): """ - Return evenly spaced values within a given interval. + This OP returns a 1-D Tensor with spaced values within a given interval. - Values are generated within the half-open interval [start, stop) (in other - words, the interval including start but excluding stop). + Values are generated into the half-open interval [``start``, ``end``) with + the ``step``. (the interval including ``start`` but excluding ``end``). - If dtype is float32 or float64, we advise adding a small epsilon to end to - avoid floating point rounding errors when comparing against end. + If ``dtype`` is float32 or float64, we advise adding a small epsilon to + ``end`` to avoid floating point rounding errors when comparing against ``end``. Parameters: - start(float|int|Variable): Start of interval. The interval includes - this value. If start is Variable, it is a 1-D Tensor with shape [1], - and it's data type should be one of int32, int64, float32, float64. - end(float|int|Variable): End of interval. The interval does not include - this value. When end is Variable, it is a 1-D Tensor with shape [1], - and it's data type should be int32, int64, float32, float64. - step(float|int|Variable): Spacing between values. For any out, this is - the istance between two adjacent values, out[i+1] - out[i]. - When end is Variable, it is a 1-D Tensor with shape [1], and it's - data type should be one of int32, int64, float32, float64. - dtype(str|np.dtype|core.VarDesc.VarType): The data type of the output - tensor, can be float32, float64, int32, int64. - name(str, optional): Normally there is no need for user to set this property. - For more information, please refer to :ref:`api_guide_Name` . - Default is None. - - Returns: a 1-D Tensor which is evenly spaced values within a given interval. - Its data type is set by dtype. - - Return type: Variable + start(float|int|Tensor): Start of interval. The interval includes this + value. If ``start`` is a Tensor, it is a 1-D Tensor with shape [1], + with data type int32, int64, float32, float64. + end(float|int|Tensor): End of interval. The interval does not include + this value. If ``end`` is a Tensor, it is a 1-D Tensor with shape + [1], with data type int32, int64, float32, float64. + step(float|int|Tensor): Spacing between values. For any out, it is + the istance between two adjacent values, out[i+1] - out[i]. If + ``step`` is a Tensor, it is a 1-D Tensor with shape [1], with data + type int32, int64, float32, float64. + dtype(str|np.dtype|core.VarDesc.VarType, optional): The data type of the + output tensor. Supported data types: int32, int64, float32, float64. + name(str, optional): The default value is None. Normally there is no + need for user to set this property. For more information, please + refer to :ref:`api_guide_Name`. + + Returns: + Tensor: A 1-D Tensor with values from the interval [``start``, ``end``) + taken with common difference ``step`` beginning from ``start``. Its + data type is set by ``dtype``. + + Raises: + TypeError: If ``dtype`` is not int32, int64, float32, float64. examples: diff --git a/python/paddle/fluid/tests/unittests/test_gaussian_random_op.py b/python/paddle/fluid/tests/unittests/test_gaussian_random_op.py index 751a5fda26..6b08c4250f 100644 --- a/python/paddle/fluid/tests/unittests/test_gaussian_random_op.py +++ b/python/paddle/fluid/tests/unittests/test_gaussian_random_op.py @@ -27,18 +27,23 @@ from op_test import OpTest class TestGaussianRandomOp(OpTest): def setUp(self): self.op_type = "gaussian_random" + self.set_attrs() self.inputs = {} self.use_mkldnn = False self.attrs = { "shape": [123, 92], - "mean": 1.0, - "std": 2., + "mean": self.mean, + "std": self.std, "seed": 10, "use_mkldnn": self.use_mkldnn } self.outputs = {'Out': np.zeros((123, 92), dtype='float32')} + def set_attrs(self): + self.mean = 1.0 + self.std = 2. + def test_check_output(self): self.check_output_customized(self.verify_output) @@ -57,6 +62,12 @@ class TestGaussianRandomOp(OpTest): "hist: " + str(hist) + " hist2: " + str(hist2)) +class TestMeanStdAreInt(TestGaussianRandomOp): + def set_attrs(self): + self.mean = 1 + self.std = 2 + + # Situation 2: Attr(shape) is a list(with tensor) class TestGaussianRandomOp_ShapeTensorList(TestGaussianRandomOp): def setUp(self): diff --git a/python/paddle/fluid/tests/unittests/test_ones_op.py b/python/paddle/fluid/tests/unittests/test_ones_op.py index 94a23b32aa..d50e820c6c 100644 --- a/python/paddle/fluid/tests/unittests/test_ones_op.py +++ b/python/paddle/fluid/tests/unittests/test_ones_op.py @@ -28,11 +28,11 @@ import numpy as np class ApiOnesTest(unittest.TestCase): def test_paddle_ones(self): with paddle.program_guard(paddle.Program()): - ones = paddle.ones(shape=[10], dtype="float64") + ones = paddle.ones(shape=[10]) place = paddle.CPUPlace() exe = paddle.Executor(place) result, = exe.run(fetch_list=[ones]) - expected_result = np.ones(10, dtype="float64") + expected_result = np.ones(10, dtype="float32") self.assertEqual((result == expected_result).all(), True) with paddle.program_guard(paddle.Program()): diff --git a/python/paddle/fluid/tests/unittests/test_uniform_random_op.py b/python/paddle/fluid/tests/unittests/test_uniform_random_op.py index 9aca04cabd..9a64dd1dee 100644 --- a/python/paddle/fluid/tests/unittests/test_uniform_random_op.py +++ b/python/paddle/fluid/tests/unittests/test_uniform_random_op.py @@ -70,6 +70,12 @@ class TestUniformRandomOp_attr_tensorlist(OpTest): hist, prob, rtol=0, atol=0.01), "hist: " + str(hist)) +class TestMaxMinAreInt(TestUniformRandomOp_attr_tensorlist): + def init_attrs(self): + self.attrs = {"min": -5, "max": 10, "seed": 10} + self.output_hist = output_hist + + class TestUniformRandomOp_attr_tensorlist_int32(OpTest): def setUp(self): self.op_type = "uniform_random" diff --git a/python/paddle/tensor/creation.py b/python/paddle/tensor/creation.py index 01a3824152..bfaf510c26 100644 --- a/python/paddle/tensor/creation.py +++ b/python/paddle/tensor/creation.py @@ -241,26 +241,29 @@ def zeros(shape, dtype=None, name=None): def zeros_like(x, dtype=None, name=None): """ :alias_main: paddle.zeros_like - :alias: paddle.zeros_like, paddle.tensor.zeros_like, paddle.tensor.creation.zeros_like + :alias: paddle.tensor.zeros_like, paddle.tensor.creation.zeros_like - This function creates a zeros tensor which has identical shape and dtype - with `input`. + This OP returns a Tensor filled with the value 0, with the same shape and + data type (use ``dtype`` if ``dtype`` is not None) as ``x``. Args: - x(Variable): The input tensor which specifies shape and dtype. The - dtype of input can be bool, float16, float32, float64, int32, int64. - dtype(np.dtype|core.VarDesc.VarType|str, optional): The data type can - be set bool, float16, float32, float64, int32, int64. The default - value is None, the dtype is the same as input. + x(Tensor): The input tensor which specifies shape and dtype. The + dtype of ``x`` can be bool, float16, float32, float64, int32, int64. + dtype(str|np.dtype|core.VarDesc.VarType, optional): The data type of the + output tensor. Supported data types: bool, float16, float32, float64, + int32, int64. If ``dtype`` is None, the data type is the same as ``x``. + Default is None. name(str, optional): The default value is None. Normally there is no need for user to set this property. For more information, please refer to :ref:`api_guide_Name`. Returns: - out(Variable): The tensor variable storing the output. + Tensor: A Tensor filled with the value 0, with the same shape and + data type (use ``dtype`` if ``dtype`` is not None) as ``x``. Raise: - TypeError: If dtype is not bool, float16, float32, float64, int32 or int64. + TypeError: If ``dtype`` is not None and is not bool, float16, float32, + float64, int32 or int64. Examples: .. code-block:: python @@ -271,8 +274,8 @@ def zeros_like(x, dtype=None, name=None): paddle.enable_imperative() x = paddle.imperative.to_variable(np.array([1,2,3], dtype='float32')) - out1 = paddle.zeros_like(x) # [1.0, 1.0, 1.0] - out2 = paddle.zeros_like(x, dtype='int32') # [1, 1, 1] + out1 = paddle.zeros_like(x) # [0., 0., 0.] + out2 = paddle.zeros_like(x, dtype='int32') # [0, 0, 0] """ return full_like(x=x, fill_value=0, dtype=dtype, name=name) @@ -388,45 +391,43 @@ def full(shape, fill_value, dtype=None, name=None): def arange(start=0, end=None, step=1, dtype=None, name=None): """ :alias_main: paddle.arange - :alias: paddle.arange,paddle.tensor.arange,paddle.tensor.creation.arange + :alias: paddle.tensor.arange, paddle.tensor.creation.arange - Return evenly spaced values within a given interval. + This OP returns a 1-D Tensor with spaced values within a given interval. - Values are generated into the half-open interval [start, stop) with the step. - (the interval including start but excluding stop). + Values are generated into the half-open interval [``start``, ``end``) with + the ``step``. (the interval including ``start`` but excluding ``end``). - If dtype is float32 or float64, we advise adding a small epsilon to end to - avoid floating point rounding errors when comparing against end. + If ``dtype`` is float32 or float64, we advise adding a small epsilon to + ``end`` to avoid floating point rounding errors when comparing against ``end``. Parameters: - start(float|int|Variable): Start of interval. The interval includes - this value. If end is None, the half-open interval is [0, start). - If start is Variable, it is a 1-D Tensor with shape [1], and it's - data type should be one of int32, int64, float32, float64. Default - is 0. - end(float|int|Variable, optional): End of interval. The interval does - not include this value. When end is Variable, it is a 1-D Tensor - with shape [1], and it's data type should be one of int32, int64, - float32, float64. If end is None, the half-open interval is [0, start). - Default is None. - step(float|int|Variable, optional): Spacing between values. For any - out, this is the istance between two adjacent values, out[i+1] - out[i]. - When end is Variable, it is a 1-D Tensor with shape [1], and it's - data type should be one of int32, int64, float32, float64. Default is 1. - dtype(str|np.dtype|core.VarDesc.VarType, optional): The data type of - the output tensor, can be float32, float64, int32, int64. If dtype - is `None` , the data type of out tensor is `int64` . Defaule is None - name(str, optional): Normally there is no need for user to set this property. - For more information, please refer to :ref:`api_guide_Name` . - Default is None. + start(float|int|Tensor): Start of interval. The interval includes this + value. If ``end`` is None, the half-open interval is [0, ``start``). + If ``start`` is a Tensor, it is a 1-D Tensor with shape [1], with + data type int32, int64, float32, float64. Default is 0. + end(float|int|Tensor, optional): End of interval. The interval does not + include this value. If ``end`` is a Tensor, it is a 1-D Tensor with + shape [1], with data type int32, int64, float32, float64. If ``end`` + is None, the half-open interval is [0, ``start``). Default is None. + step(float|int|Tensor, optional): Spacing between values. For any out, + it is the istance between two adjacent values, out[i+1] - out[i]. + If ``step`` is a Tensor, it is a 1-D Tensor with shape [1], with + data type int32, int64, float32, float64. Default is 1. + dtype(str|np.dtype|core.VarDesc.VarType, optional): The data type of the + output tensor. Supported data types: int32, int64, float32, float64. + If ``dytpe`` is None, the data type is float32. Default is None. + name(str, optional): The default value is None. Normally there is no + need for user to set this property. For more information, please + refer to :ref:`api_guide_Name`. - Returns: a 1-D Tensor which is evenly spaced values within a given interval. - Its data type is set by dtype. - - Return type: Variable + Returns: + Tensor: A 1-D Tensor with values from the interval [``start``, ``end``) + taken with common difference ``step`` beginning from ``start``. Its + data type is set by ``dtype``. Raises: - TypeError: If dtype is not float32, float64, int32 or int64. + TypeError: If ``dtype`` is not int32, int64, float32, float64. examples: diff --git a/python/paddle/tensor/random.py b/python/paddle/tensor/random.py index eac99163e0..5e9f55cd34 100644 --- a/python/paddle/tensor/random.py +++ b/python/paddle/tensor/random.py @@ -40,38 +40,40 @@ __all__ = [ def randint(low=0, high=None, shape=[1], dtype=None, name=None): """ :alias_main: paddle.randint - :alias: paddle.randint,paddle.tensor.randint,paddle.tensor.random.randint + :alias: paddle.tensor.randint, paddle.tensor.random.randint - This function returns a Tensor filled with random integers from the - "discrete uniform" distribution of the specified data type in the interval - [low, high). If high is None (the default), then results are from [0, low). + This OP returns a Tensor filled with random integers from a discrete uniform + distribution in the range [``low``, ``high``), with ``shape`` and ``dtype``. + If ``high`` is None (the default), the range is [0, ``low``). Args: - low (int): The lower bound on the range of random values to generate, - the low is included in the range.(unless high=None, in which case - this parameter is one above the highest such integer). Default is 0. - high (int, optional): The upper bound on the range of random values to - generate, the high is excluded in the range. Default is None(see - above for behavior if high=None). - shape (list|tuple|Variable, optional): The shape of the output Tensor, - if the shape is a list or tuple, its elements can be an integer or - a Tensor with the shape [1], and the type of the Tensor must be - int32 or int64. If the shape is a Variable, it is a 1-D Tensor, - and the type of the Tensor must be int32 or int64. Default is None. - dtype(np.dtype|core.VarDesc.VarType|str, optional): Data type of the - output Tensor which can be int32, int64. If dtype is `None`, the - data type of created Tensor is `int64` + low(int): The lower bound on the range of random values to generate. + The ``low`` is included in the range. If ``high`` is None, the + range is [0, ``low``). Default is 0. + high(int, optional): The upper bound on the range of random values to + generate, the ``high`` is excluded in the range. Default is None + (see above for behavior if high = None). Default is None. + shape(list|tuple|Tensor): The shape of the output Tensor. If ``shape`` + is a list or tuple, the elements of it should be integers or Tensors + (with the shape [1], and the data type int32 or int64). If ``shape`` + is a Tensor, it should be a 1-D Tensor(with the data type int32 or + int64). Default is [1]. + dtype(str|np.dtype|core.VarDesc.VarType, optional): The data type of the + output tensor. Supported data types: int32, int64. If ``dytpe`` + is None, the data type is int64. Default is None. name(str, optional): The default value is None. Normally there is no need for user to set this property. For more information, please refer to :ref:`api_guide_Name`. Returns: - Variable: A Tensor of the specified shape filled with random integers. + Tensor: A Tensor filled with random integers from a discrete uniform + distribution in the range [``low``, ``high``), with ``shape`` and ``dtype``. Raises: - TypeError: If shape's type is not list, tuple or Variable. - TypeError: If dtype is not int32 or int64. - ValueError: If low is not large then high; If low is 0, and high is None. + TypeError: If ``shape`` is not list, tuple, Tensor. + TypeError: If ``dtype`` is not int32, int64. + ValueError: If ``high`` is not greater then ``low``; If ``high`` is + None, and ``low`` is not greater than 0. Examples: .. code-block:: python @@ -82,29 +84,28 @@ def randint(low=0, high=None, shape=[1], dtype=None, name=None): paddle.enable_imperative() # example 1: - # attr shape is a list which doesn't contain tensor Variable. + # attr shape is a list which doesn't contain Tensor. result_1 = paddle.randint(low=-5, high=5, shape=[3]) - # [0 -3 2] + # [0, -3, 2] # example 2: - # attr shape is a list which contains tensor Variable. - dim_1 = paddle.fill_constant([1],"int64",2) - dim_2 = paddle.fill_constant([1],"int32",3) + # 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]] + # [[0, -1, -3], + # [4, -2, 0]] # example 3: - # attr shape is a Variable + # 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] + # [-2, 2, 3] # example 4: # data type is int32 result_4 = paddle.randint(low=-5, high=5, shape=[3], dtype='int32') - # [-5 4 -4] + # [-5, 4, -4] # example 5: # Input only one parameter @@ -152,34 +153,33 @@ def randint(low=0, high=None, shape=[1], dtype=None, name=None): def randn(shape, dtype=None, name=None): """ :alias_main: paddle.randn - :alias: paddle.randn,paddle.tensor.randn,paddle.tensor.random.randn + :alias: paddle.tensor.randn, paddle.tensor.random.randn - This function returns a tensor filled with random numbers from a normal - distribution with mean 0 and standard deviation 1 (also called the standard normal - distribution). + This OP returns a Tensor filled with random values sampled from a normal + distribution with mean 0 and standard deviation 1 (also called the standard + normal distribution), with ``shape`` and ``dtype``. Args: - shape(list|tuple|Variable): Shape of the Tensor to be created. The data - type is ``int32`` or ``int64`` . If ``shape`` is a list or tuple, - the elements of it should be integers or Tensors with shape [1]. If - ``shape`` is a Variable, it should be an 1-D Tensor . - dtype(np.dtype|core.VarDesc.VarType|str, optional): Data type of the output - tensor, which can be float32, float64. If dtype is `None` , the data - type of output tensor is `float32` . Default is None. - name(str, optional): Normally there is no need for user to set this property. - For more information, please refer to :ref:`api_guide_Name` . - Default is None. + shape(list|tuple|Tensor): The shape of the output Tensor. If ``shape`` + is a list or tuple, the elements of it should be integers or Tensors + (with the shape [1], and the data type int32 or int64). If ``shape`` + is a Tensor, it should be a 1-D Tensor(with the data type int32 or + int64). + dtype(str|np.dtype|core.VarDesc.VarType, optional): The data type of the + output tensor. Supported data types: float32, float64. If ``dytpe`` + is None, the data type is float32. Default is None. + name(str, optional): The default value is None. Normally there is no + need for user to set this property. For more information, please + refer to :ref:`api_guide_Name`. Returns: - Random tensor whose data is drawn from a standard normal distribution, - dtype: flaot32 or float64 as specified. - - Return type: Variable + Tensor: A Tensor filled with random values sampled from a normal + distribution with mean 0 and standard deviation 1 (also called the + standard normal distribution), with ``shape`` and ``dtype``. Raises: - TypeError: If the type of `shape` is not Variable, list or tuple. - TypeError: If the data type of `dtype` is not float32 or float64. - ValueError: If the length of `shape` is not bigger than 0. + TypeError: If ``shape`` is not list, tuple, Tensor. + TypeError: If ``dtype`` is not float32, float64. Examples: .. code-block:: python @@ -189,27 +189,27 @@ def randn(shape, dtype=None, name=None): paddle.enable_imperative() - # example 1: attr shape is a list which doesn't contain tensor Variable. + # 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 ]] + # [[-2.923464 , 0.11934398, -0.51249987], + # [ 0.39632758, 0.08177969, 0.2692008 ]] - # example 2: attr shape is a list which contains tensor Variable. + # 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 ]]] - - # example 3: attr shape is a Variable, the data type must be int64 or int32. + # [[[-2.8852394 , -0.25898588], + # [-0.47420555, 0.17683524], + # [-0.7989969 , 0.00754541]], + # [[ 0.85201347, 0.32320443], + # [ 1.1399018 , 0.48336947], + # [ 0.8086993 , 0.6868893 ]]] + + # 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 ]] + # [[-2.878077 , 0.17099959, 0.05111201] + # [-0.3761474, -1.044801 , 1.1870178 ]] """ if dtype is None: @@ -225,24 +225,27 @@ def randn(shape, dtype=None, name=None): def randperm(n, dtype="int64", name=None): """ :alias_main: paddle.randperm - :alias: paddle.randperm,paddle.tensor.randperm,paddle.tensor.random.randperm + :alias: paddle.tensor.randperm, paddle.tensor.random.randperm - ${comment} + This OP returns a 1-D Tensor filled with random permutation values from 0 + to n-1, with ``dtype``. Args: n(int): The upper bound (exclusive), and it should be greater than 0. - dtype(np.dtype|core.VarDesc.VarType|str, optional): The type of the - output Tensor. Supported data types: int32, int64, float32, float64. - Default: int32. - name(str, optional): Normally there is no need for user to set this property. - For more information, please refer to :ref:`api_guide_Name` . - Default is None. + dtype(str|np.dtype|core.VarDesc.VarType, optional): The data type of + the output Tensor. Supported data types: int32, int64, float32, + float64. Default is int64. + name(str, optional): The default value is None. Normally there is no + need for user to set this property. For more information, please + refer to :ref:`api_guide_Name`. Returns: - ${out_comment}. + Tensor: A 1-D Tensor filled with random permutation values from 0 + to n-1, with ``dtype``. - Return Type: - ${out_type} + Raises: + ValueError: If ``n`` is not greater than 0. + TypeError: If ``dtype`` is not int32, int64, float32, float64. Examples: .. code-block:: python @@ -252,10 +255,10 @@ def randperm(n, dtype="int64", name=None): paddle.enable_imperative() result_1 = paddle.randperm(5) - # [4 1 2 3 0] + # [4, 1, 2, 3, 0] result_2 = paddle.randperm(7, 'int32') - # [1 6 2 0 4 3 5] + # [1, 6, 2, 0, 4, 3, 5] """ if not isinstance(dtype, core.VarDesc.VarType): @@ -281,10 +284,10 @@ def randperm(n, dtype="int64", name=None): def rand(shape, dtype=None, name=None): """ :alias_main: paddle.rand - :alias: paddle.rand,paddle.tensor.rand,paddle.tensor.random.rand + :alias: paddle.tensor.rand, paddle.tensor.random.rand - This OP initializes a variable with random values sampled from a - uniform distribution in the range [0, 1). + This OP returns a Tensor filled with random values sampled from a uniform + distribution in the range [0, 1), with ``shape`` and ``dtype``. Examples: :: @@ -296,22 +299,25 @@ def rand(shape, dtype=None, name=None): result=[[0.8505902, 0.8397286]] Args: - shape(list|tuple|Variable): Shape of the Tensor to be created. The data - type is ``int32`` or ``int64`` . If ``shape`` is a list or tuple, - the elements of it should be integers or Tensors with shape [1]. If - ``shape`` is a Variable, it should be an 1-D Tensor . - dtype(np.dtype|core.VarDesc.VarType|str, optional): Data type of the - output tensor which can be float32, float64, if dytpe is `None`, - the data type of created tensor is `float32` + shape(list|tuple|Tensor): The shape of the output Tensor. If ``shape`` + is a list or tuple, the elements of it should be integers or Tensors + (with the shape [1], and the data type int32 or int64). If ``shape`` + is a Tensor, it should be a 1-D Tensor(with the data type int32 or + int64). + dtype(str|np.dtype|core.VarDesc.VarType, optional): The data type of the + output tensor. Supported data types: float32, float64. If ``dytpe`` + is None, the data type is float32. Default is None. name(str, optional): The default value is None. Normally there is no need for user to set this property. For more information, please refer to :ref:`api_guide_Name`. + Returns: - Variable: A Tensor of the specified shape filled with random numbers - from a uniform distribution on the interval [0, 1). + Tensor: A Tensor filled with random values sampled from a uniform + distribution in the range [0, 1), with ``shape`` and ``dtype``. Raises: - TypeError: The shape type should be list or tupple or Variable. + TypeError: If ``shape`` is not list, tuple, Tensor. + ValueError: If ``dtype`` is not float32, float64. Examples: .. code-block:: python @@ -320,27 +326,27 @@ def rand(shape, dtype=None, name=None): import numpy as np paddle.enable_imperative() - # example 1: attr shape is a list which doesn't contain tensor Variable. + # 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 ]] - # example 2: attr shape is a list which contains tensor Variable. + # 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 ]]] - - # example 3: attr shape is a Variable, the data type must be int64 or int32. + # [[[0.8879919 , 0.25788337], + # [0.28826773, 0.9712097 ], + # [0.26438272, 0.01796806]], + # [[0.33633623, 0.28654453], + # [0.79109055, 0.7305809 ], + # [0.870881 , 0.2984597 ]]] + + # 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 ]] + # [[0.22920267, 0.841956 , 0.05981819], + # [0.4836288 , 0.24573246, 0.7516129 ]] """ if dtype is None: -- GitLab