mindspore 2.0.0rc1__cp38-none-any.whl → 2.2.0__cp38-none-any.whl

mindspore/nn/layer/basic.py

@@ -24,7 +24,7 @@ from mindspore import context, log as logger
 from mindspore.ops.composite.multitype_ops import _constexpr_utils as const_utils
 from mindspore.common.seed import _get_graph_seed
 from mindspore.common.tensor import Tensor
-from mindspore.common.initializer import initializer
+from mindspore.common.initializer import initializer, HeUniform, Uniform
 from mindspore.ops import operations as P
 from mindspore.ops import functional as F
 from mindspore.ops.operations import _inner_ops as inner
@@ -75,9 +75,11 @@ class L1Regularizer(Cell):
         ``Ascend`` ``GPU`` ``CPU``
 
     Examples:
+        >>> import mindspore as ms
+        >>> import numpy as np
         >>> scale = 0.5
-        >>> net = nn.L1Regularizer(scale)
-        >>> weights = Tensor(np.array([[1.0, -2.0], [-3.0, 4.0]]).astype(np.float32))
+        >>> net = ms.nn.L1Regularizer(scale)
+        >>> weights = ms.Tensor(np.array([[1.0, -2.0], [-3.0, 4.0]]).astype(np.float32))
         >>> output = net(weights)
         >>> print(output.asnumpy())
         5.0
@@ -108,8 +110,9 @@ class Dropout(Cell):
     r"""
     Dropout layer for the input.
 
-    Dropout is a regularization method. The operator randomly sets some neurons output to 0
-    according to the probability of discarding the probability of discarding.
+    Dropout is a means of regularization that reduces overfitting by preventing correlations between neuronal nodes.
+    The operator randomly sets some neurons output to 0 according to `p`, which means the probability of discarding
+    during training. And the return will be multiplied by :math:`\frac{1}{1-p}` during training.
     During the reasoning, this layer returns the same Tensor as the `x`.
 
     This technique is proposed in paper `Dropout: A Simple Way to Prevent Neural Networks from Overfitting
@@ -126,10 +129,10 @@ class Dropout(Cell):
 
     Args:
         keep_prob (float): Deprecated. The keep rate, greater than 0 and less equal than 1.
-            E.g. rate=0.9, dropping out 10% of input neurons. Default: 0.5.
+            E.g. rate=0.9, dropping out 10% of input neurons. Default: ``0.5`` .
         p (Union[float, int, None]): The dropout rate, greater than or equal to 0 and less than 1.
-            E.g. rate=0.9, dropping out 90% of input neurons. Default: None.
-        dtype (:class:`mindspore.dtype`): Data type of `input`. Default: mindspore.float32.
+            E.g. rate=0.9, dropping out 90% of input neurons. Default: ``None`` .
+        dtype (:class:`mindspore.dtype`): Data type of `input`. Default: ``mstype.float32`` .
 
     Inputs:
         - **x** (Tensor) - The input of Dropout with data type of float16 or float32.
@@ -149,6 +152,9 @@ class Dropout(Cell):
         ``Ascend`` ``GPU`` ``CPU``
 
     Examples:
+        >>> import mindspore
+        >>> from mindspore import Tensor, nn
+        >>> import numpy as np
         >>> x = Tensor(np.ones([2, 2, 3]), mindspore.float32)
         >>> net = nn.Dropout(p=0.2)
         >>> net.set_train()
@@ -216,7 +222,7 @@ class Dropout1d(Cell):
 
     Args:
         p (float, optional): The dropping probability of a channel, between 0 and 1, e.g. `p` = 0.8,
-            which means an 80% chance of being set to 0. Default: 0.5.
+            which means an 80% chance of being set to 0. Default: ``0.5`` .
 
     Inputs:
         - **x** (Tensor) - A tensor with shape :math:`(N, C, L)` or :math:`(C, L)`, where `N` is the batch size,
@@ -224,7 +230,7 @@ class Dropout1d(Cell):
           int64, float16, float32 or float64.
 
     Outputs:
-        Tensor, output, with the same shape and data type as `x`.
+        Tensor, has the same shape and data type as `x`.
 
     Raises:
         TypeError: If `x` is not a Tensor.
@@ -238,10 +244,9 @@ class Dropout1d(Cell):
     Examples:
         >>> import numpy as np
         >>> import mindspore as ms
-        >>> from mindspore import nn, Tensor
-        >>> op = nn.Dropout1d(p=0.6)
+        >>> op = ms.nn.Dropout1d(p=0.6)
         >>> op.training = True
-        >>> a = Tensor(np.ones((3, 3)), ms.float32)
+        >>> a = ms.Tensor(np.ones((3, 3)), ms.float32)
         >>> output = op(a)
     """
 
@@ -281,6 +286,9 @@ class Dropout2d(Cell):
         ``Ascend`` ``GPU`` ``CPU``
 
     Examples:
+        >>> import mindspore
+        >>> from mindspore import Tensor, nn
+        >>> import numpy as np
         >>> dropout = nn.Dropout2d(p=0.5)
         >>> x = Tensor(np.ones([2, 1, 2, 3]), mindspore.float32)
         >>> output = dropout(x)
@@ -306,7 +314,7 @@ class Dropout2d(Cell):
         return out
 
     def extend_repr(self):
-        return 'p={}'.format(self.keep_prob)
+        return f"p={self.keep_prob}"
 
 
 class Dropout3d(Cell):
@@ -329,6 +337,9 @@ class Dropout3d(Cell):
         ``Ascend`` ``GPU`` ``CPU``
 
     Examples:
+        >>> import mindspore
+        >>> from mindspore import Tensor, nn
+        >>> import numpy as np
         >>> dropout = nn.Dropout3d(p=0.5)
         >>> x = Tensor(np.ones([2, 1, 2, 1, 2]), mindspore.float32)
         >>> output = dropout(x)
@@ -354,7 +365,7 @@ class Dropout3d(Cell):
         return out
 
     def extend_repr(self):
-        return 'p={}'.format(self.keep_prob)
+        return f'p={self.keep_prob}'
 
 
 class Upsample(Cell):
@@ -365,8 +376,9 @@ class Upsample(Cell):
         ``Ascend`` ``GPU`` ``CPU``
 
     Examples:
-        >>> x = Tensor([[[[1.0, 2.0, 3.0, 4.0], [5.0, 6.0, 7.0, 8.0]]]])
-        >>> upsample = nn.Upsample(size=(5, 5))
+        >>> import mindspore as ms
+        >>> x = ms.Tensor([[[[1.0, 2.0, 3.0, 4.0], [5.0, 6.0, 7.0, 8.0]]]])
+        >>> upsample = ms.nn.Upsample(size=(5, 5))
         >>> out = upsample(x)
         >>> print(x.asnumpy())
         [[[[1. 2. 3. 4.]
@@ -401,8 +413,8 @@ class Flatten(Cell):
     Flatten the input Tensor along dimensions from `start_dim` to `end_dim`.
 
     Args:
-        start_dim (int, optional): The first dimension to flatten. Default: 1.
-        end_dim (int, optional): The last dimension to flatten. Default: -1.
+        start_dim (int, optional): The first dimension to flatten. Default: ``1`` .
+        end_dim (int, optional): The last dimension to flatten. Default: ``-1`` .
 
     Inputs:
         - **x** (Tensor) - The input Tensor to be flattened.
@@ -421,6 +433,9 @@ class Flatten(Cell):
         ``Ascend`` ``GPU`` ``CPU``
 
     Examples:
+        >>> import mindspore
+        >>> from mindspore import Tensor, nn
+        >>> import numpy as np
         >>> x = Tensor(np.array([[[1.2, 1.2], [2.1, 2.1]], [[2.2, 2.2], [3.2, 3.2]]]), mindspore.float32)
         >>> net = nn.Flatten()
         >>> output = net(x)
@@ -439,13 +454,15 @@ class Flatten(Cell):
         self.start_dim = start_dim
         self.end_dim = end_dim
 
+    def check_axis_valid(self, axis, ndim):
+        if axis < -ndim or axis >= ndim:
+            raise ValueError("'start_dim' or 'end_dim' out of range.")
+
     def construct(self, x):
         x_rank = F.rank(x)
         ndim = x_rank if x_rank != 0 else 1
-        if self.start_dim < -ndim or self.start_dim >= ndim:
-            const_utils.raise_value_error("'start_dim' out of range.")
-        if self.end_dim < -ndim or self.end_dim >= ndim:
-            const_utils.raise_value_error("'end_dim' out of range.")
+        self.check_axis_valid(self.start_dim, ndim)
+        self.check_axis_valid(self.end_dim, ndim)
         return F.flatten(x, start_dim=self.start_dim, end_dim=self.end_dim)
 
 
@@ -458,22 +475,22 @@ def check_dense_input_shape(x, prim_name=None):
 
 
 class Identity(Cell):
-    """
-    Returns a Tensor with the same shape and contents as input.
+    r"""
+    A placeholder identity operator that returns the same as input.
 
     Inputs:
-        - **x** (Tensor) - The shape of tensor is :math:`(x_1, x_2, ..., x_R)`. The data type is Number.
+        - **x** (Any) - The input of Identity.
 
     Outputs:
-        Tensor, the shape of tensor and the data type are the same as `x`.
-
-    Raises:
-        TypeError: If `x` is not a Tensor.
+        The same as `x`.
 
     Supported Platforms:
         ``Ascend`` ``GPU`` ``CPU``
 
     Examples:
+        >>> import mindspore
+        >>> from mindspore import Tensor, nn
+        >>> import numpy as np
         >>> x = Tensor(np.array([1, 2, 3, 4]), mindspore.int64)
         >>> net = nn.Identity()
         >>> output = net(x)
@@ -484,11 +501,9 @@ class Identity(Cell):
     def __init__(self):
         """Initialize Identity."""
         super(Identity, self).__init__()
-        self.identity = P.Identity()
 
     def construct(self, x):
-        out = self.identity(x)
-        return out
+        return x
 
 
 class Dense(Cell):
@@ -509,13 +524,16 @@ class Dense(Cell):
         in_channels (int): The number of channels in the input space.
         out_channels (int): The number of channels in the output space.
         weight_init (Union[Tensor, str, Initializer, numbers.Number]): The trainable weight_init parameter. The dtype
-            is same as `x`. The values of str refer to the function `initializer`. Default: 'normal'.
+            is same as `x`. The values of str refer to the function `initializer`. Default: ``None`` ,
+            weight will be initialized using HeUniform.
         bias_init (Union[Tensor, str, Initializer, numbers.Number]): The trainable bias_init parameter. The dtype is
-            same as `x`. The values of str refer to the function `initializer`. Default: 'zeros'.
-        has_bias (bool): Specifies whether the layer uses a bias vector :math:`\text{bias}`. Default: True.
+            same as `x`. The values of str refer to the function `initializer`. Default: ``None`` ,
+            bias will be initialized using Uniform.
+        has_bias (bool): Specifies whether the layer uses a bias vector :math:`\text{bias}`. Default: ``True``.
         activation (Union[str, Cell, Primitive, None]): activate function applied to the output of the fully connected
             layer. Both activation name, e.g. 'relu', and mindspore activation function, e.g. mindspore.ops.ReLU(),
-            are supported. Default: None.
+            are supported. Default: ``None`` .
+        dtype (:class:`mindspore.dtype`): Data type of Parameter. Default: ``mstype.float32`` .
 
     Inputs:
         - **x** (Tensor) - Tensor of shape :math:`(*, in\_channels)`. The `in_channels` in `Args` should be equal
@@ -537,6 +555,9 @@ class Dense(Cell):
         ``Ascend`` ``GPU`` ``CPU``
 
     Examples:
+        >>> import mindspore
+        >>> from mindspore import Tensor, nn
+        >>> import numpy as np
         >>> x = Tensor(np.array([[180, 234, 154], [244, 48, 247]]), mindspore.float32)
         >>> net = nn.Dense(3, 4)
         >>> output = net(x)
@@ -548,10 +569,11 @@ class Dense(Cell):
     def __init__(self,
                  in_channels,
                  out_channels,
-                 weight_init='normal',
-                 bias_init='zeros',
+                 weight_init=None,
+                 bias_init=None,
                  has_bias=True,
-                 activation=None):
+                 activation=None,
+                 dtype=mstype.float32):
         """Initialize Dense."""
         super(Dense, self).__init__()
         self.in_channels = Validator.check_positive_int(
@@ -570,8 +592,10 @@ class Dense(Cell):
                                  f"be equal to 2, and the first dim must be equal to 'out_channels', and the "
                                  f"second dim must be equal to 'in_channels'. But got 'weight_init': {weight_init}, "
                                  f"'out_channels': {out_channels}, 'in_channels': {in_channels}.")
+        if weight_init is None:
+            weight_init = HeUniform(math.sqrt(5))
         self.weight = Parameter(initializer(
-            weight_init, [out_channels, in_channels]), name="weight")
+            weight_init, [out_channels, in_channels], dtype=dtype), name="weight")
 
         self.bias = None
         if self.has_bias:
@@ -580,8 +604,11 @@ class Dense(Cell):
                     raise ValueError(f"For '{self.cls_name}', bias init shape error. The ndim of 'bias_init' must "
                                      f"be equal to 1, and the first dim must be equal to 'out_channels'. But got "
                                      f"'bias_init': {bias_init}, 'out_channels': {out_channels}.")
+            if bias_init is None:
+                bound = 1 / math.sqrt(in_channels)
+                bias_init = Uniform(scale=bound)
             self.bias = Parameter(initializer(
-                bias_init, [out_channels]), name="bias")
+                bias_init, [out_channels], dtype=dtype), name="bias")
             self.bias_add = P.BiasAdd()
 
         self.matmul = P.MatMul(transpose_b=True)
@@ -608,12 +635,11 @@ class Dense(Cell):
         return x
 
     def extend_repr(self):
-        s = 'input_channels={}, output_channels={}'.format(
-            self.in_channels, self.out_channels)
+        s = f'input_channels={self.in_channels}, output_channels={self.out_channels}'
         if self.has_bias:
-            s += ', has_bias={}'.format(self.has_bias)
+            s += f', has_bias={self.has_bias}'
         if self.activation_flag:
-            s += ', activation={}'.format(self.activation)
+            s += f', activation={self.activation}'
         return s
 
 
@@ -660,7 +686,7 @@ class ClipByNorm(Cell):
 
     Args:
         axis (Union[None, int, tuple(int)]): Compute the L2-norm along the Specific dimension.
-                                            Default: None, all dimensions to calculate.
+                                            Default: ``None`` , all dimensions to calculate.
 
     Inputs:
         - **x** (Tensor) - Tensor of shape N-D. The type must be float32 or float16.
@@ -678,6 +704,9 @@ class ClipByNorm(Cell):
         ``Ascend`` ``GPU`` ``CPU``
 
     Examples:
+        >>> import mindspore
+        >>> from mindspore import Tensor, nn
+        >>> import numpy as np
         >>> net = nn.ClipByNorm()
         >>> x = Tensor(np.random.randint(0, 10, [4, 16]), mindspore.float32)
         >>> clip_norm = Tensor(np.array([100]).astype(np.float32))
@@ -699,8 +728,8 @@ class ClipByNorm(Cell):
 
 class Norm(Cell):
     r"""
-    'nn.Norm' is deprecated from version 2.0 and will be removed in a future version,
-    use 'ops.norm' instead.
+    The Norm class will be deprecated in the future,
+    this function can be replaced by :func:`ops.norm`
     """
 
     @deprecated("2.0", "ops.norm", False)
@@ -723,13 +752,13 @@ class Norm(Cell):
         return x
 
     def extend_repr(self):
-        return 'axis={}, keep_dims={}'.format(self.axis, self.keep_dims)
+        return f'axis={self.axis}, keep_dims={self.keep_dims}'
 
 
 class OneHot(Cell):
     """
-    'nn.OneHot' is deprecated from version 2.0 and will be removed in a future version,
-    use 'ops.one_hot' instead.
+    The OneHot class will be deprecated in the future,
+    this function can be replaced by :func:`ops.one_hot`
     """
 
     @deprecated("2.0", "ops.one_hot", False)
@@ -769,8 +798,8 @@ class Pad(Cell):
                 # 2nd dimension of output is paddings[1][0] + 3 + paddings[1][1] = 2 + 3 + 2 = 7.
                 # So the shape of output is (5, 7).
 
-        mode (str): Specifies padding mode. The optional values are "CONSTANT", "REFLECT", "SYMMETRIC".
-            Default: "CONSTANT".
+        mode (str): Specifies padding mode. The optional values are ``"CONSTANT"`` , ``"REFLECT"`` , ``"SYMMETRIC"`` .
+            Default: ``"CONSTANT"`` .
 
     Inputs:
         - **x** (Tensor) - The input tensor.
@@ -792,14 +821,14 @@ class Pad(Cell):
     Raises:
         TypeError: If `paddings` is not a tuple.
         ValueError: If length of `paddings` is more than 4 or its shape is not :math:`(N, 2)` .
-        ValueError: If `mode` is not one of 'CONSTANT', 'REFLECT', 'SYMMETRIC'.
+        ValueError: If `mode` is not one of ``"CONSTANT"``, ``"REFLECT"``, ``"SYMMETRIC"``.
 
     Supported Platforms:
         ``Ascend`` ``GPU`` ``CPU``
 
     Examples:
-        >>> from mindspore import Tensor
-        >>> import mindspore.nn as nn
+        >>> import mindspore
+        >>> from mindspore import Tensor, nn, ops
         >>> import numpy as np
         >>> # If `mode` is "CONSTANT"
         >>> class Net(nn.Cell):
@@ -912,7 +941,7 @@ class Pad(Cell):
         return x
 
 
-@constexpr
+@_primexpr
 def bilinear(shape, size, scale, align_corners, prim_name=None):
     """Check input and calculate shape"""
     msg_prefix = f"For '{prim_name}', the" if prim_name else "The"
@@ -945,6 +974,8 @@ class ResizeBilinear(Cell):
         Deprecated
 
     Examples:
+        >>> import mindspore
+        >>> from mindspore import Tensor, nn
         >>> x = Tensor([[[[1, 2, 3, 4], [5, 6, 7, 8]]]], mindspore.float32)
         >>> resize_bilinear = nn.ResizeBilinear()
         >>> result = resize_bilinear(x, size=(5,5))
@@ -988,20 +1019,22 @@ class Unfold(Cell):
             must be a tuple or list of int, and the format is [1, stride_row, stride_col, 1].
         rates (Union[tuple[int], list[int]]): In each extracted patch, the gap between the corresponding dimension
             pixel positions, must be a tuple or a list of integers, and the format is [1, rate_row, rate_col, 1].
-        padding (str): The type of padding algorithm, is a string whose value is "same" or "valid", not case sensitive.
-            Default: "valid".
+        padding (str): The type of padding algorithm, is a string whose value is ``"same"`` or ``"valid"`` , not case
+            sensitive. Default: ``"valid"`` .
 
-            - same: Means that the patch can take the part beyond the original image, and this part is filled with 0.
+            - ``"same"``: Means that the patch can take the part beyond the original image, and this part is filled
+              with 0.
 
-            - valid: Means that the taken patch area must be completely covered in the original image.
+            - ``"valid"``: Means that the taken patch area must be completely covered in the original image.
 
     Inputs:
-        - **x** (Tensor) - A 4-D tensor whose shape is [in_batch, in_depth, in_row, in_col] and
-          data type is number.
+        - **x** (Tensor) - A 4-D tensor whose shape is :math:`[in\_batch, in\_depth, in\_row, in\_col]`
+          and data type is number.
 
     Outputs:
         Tensor, a 4-D tensor whose data type is same as `x`,
-        and the shape is [out_batch, out_depth, out_row, out_col] where `out_batch` is the same as the `in_batch`.
+        and the shape is :math:`(out\_batch, out\_depth, out\_row, out\_col)`
+        where `out_batch` is the same as the `in_batch`.
 
         - :math:`out\_depth = ksize\_row * ksize\_col * in\_depth`
         - :math:`out\_row = (in\_row - (ksize\_row + (ksize\_row - 1) * (rate\_row - 1))) // stride\_row + 1`
@@ -1009,17 +1042,20 @@ class Unfold(Cell):
 
     Raises:
         TypeError: If `ksizes`, `strides` or `rates` is neither a tuple nor list.
-        ValueError: If shape of `ksizes`, `strides` or `rates` is not (1, x_row, x_col, 1).
+        ValueError: If shape of `ksizes`, `strides` or `rates` is not :math:`(1, x\_row, x\_col, 1)`.
         ValueError: If the second and third element of `ksizes`, `strides` or `rates` is less than 1.
 
     Supported Platforms:
         ``Ascend`` ``GPU``
 
     Examples:
-        >>> net = Unfold(ksizes=[1, 2, 2, 1], strides=[1, 2, 2, 1], rates=[1, 2, 2, 1])
+        >>> import mindspore
+        >>> from mindspore import Tensor, nn
+        >>> import numpy as np
+        >>> net = nn.Unfold(ksizes=[1, 2, 2, 1], strides=[1, 2, 2, 1], rates=[1, 2, 2, 1])
         >>> # As stated in the above code:
         >>> # ksize_row = 2, ksize_col = 2, rate_row = 2, rate_col = 2, stride_row = 2, stride_col = 2.
-        >>> image = Tensor(np.ones([2, 3, 6, 6]), dtype=mstype.float16)
+        >>> image = Tensor(np.ones([2, 3, 6, 6]), dtype=mindspore.float16)
         >>> # in_batch = 2, in_depth = 3, in_row = 6, in_col = 6.
         >>> # Substituting the formula to get:
         >>> # out_batch = in_batch = 2
@@ -1041,7 +1077,8 @@ class Unfold(Cell):
             if len(arg_val) != 4 or arg_val[0] != 1 or arg_val[3] != 1:
                 raise ValueError(f"For '{prim_name}' the format of '{arg_name}s' must be [1, {arg_name}_row, "
                                  f"{arg_name}_col, 1], but got {arg_val}.")
-            if not isinstance(arg_val[1], int) or not isinstance(arg_val[2], int) or arg_val[1] < 1 or arg_val[2] < 1:
+            is_int = isinstance(arg_val[1], int) and isinstance(arg_val[2], int)
+            if not is_int or arg_val[1] < 1 or arg_val[2] < 1:
                 raise ValueError(f"For '{prim_name}' the {arg_name}_row and {arg_name}_col in '{arg_name}s' must be "
                                  f"an positive integer number, but got {arg_name}_row is {arg_val[1]}, "
                                  f"{arg_name}_col is {arg_val[2]}")
@@ -1070,8 +1107,8 @@ def tril(x_shape, x_dtype, k):
 
 class Tril(Cell):
     """
-    'nn.Tril' is deprecated from version 2.0 and will be removed in a future version,
-    use 'ops.tril' instead.
+    The Tril class will be deprecated in the future,
+    this function can be replaced by :func:`ops.tril`
     """
 
     @deprecated("2.0", "ops.tril", False)
@@ -1099,8 +1136,8 @@ def triu(x_shape, x_dtype, k):
 
 class Triu(Cell):
     """
-    'nn.Triu' is deprecated from version 2.0 and will be removed in a future version,
-    use 'ops.triu' instead.
+    The Triu class will be deprecated in the future,
+    this function can be replaced by :func:`ops.triu`
     """
 
     @deprecated("2.0", "ops.triu", False)
@@ -1149,8 +1186,8 @@ def _get_matrix_diag_part_assist(x_shape, x_dtype):
 
 class MatrixDiag(Cell):
     r"""
-    'nn.MatrixDiag' is deprecated from version 2.0 and will be removed in a future version,
-    use 'ops.diag' instead.
+    The MatrixDiag class will be deprecated in the future,
+    this function can be replaced by :func:`ops.diag`
     """
 
     @deprecated("2.0", "ops.diag", False)
@@ -1170,8 +1207,8 @@ class MatrixDiag(Cell):
 
 class MatrixDiagPart(Cell):
     r"""
-    'nn.MatrixDiagPart' is deprecated from version 2.0 and will be removed in a future version,
-    use 'ops.diagonal' instead.
+    The MatrixDiagPart class will be deprecated in the future,
+    this function can be replaced by :func:`ops.diagonal`
     """
 
     @deprecated("2.0", "ops.diagonal", False)
@@ -1221,6 +1258,8 @@ class MatrixSetDiag(Cell):
         ``Ascend``
 
     Examples:
+        >>> import mindspore
+        >>> from mindspore import Tensor, nn
         >>> x = Tensor([[[-1, 0], [0, 1]], [[-1, 0], [0, 1]], [[-1, 0], [0, 1]]], mindspore.float32)
         >>> diagonal = Tensor([[-1., 2.], [-1., 1.], [-1., 1.]], mindspore.float32)
         >>> matrix_set_diag = nn.MatrixSetDiag()
@@ -1255,8 +1294,8 @@ def _check_input_dim(axis, dim, cls_name):
 
 class Roll(Cell):
     """
-    'nn.Roll' is deprecated from version 2.0 and will be removed in a future version,
-    use 'ops.roll' instead.
+    The Roll class will be deprecated in the future,
+    this function can be replaced by :func:`ops.roll`
     """
 
     @deprecated("2.0", "ops.roll", False)
@@ -1350,6 +1389,9 @@ class Unflatten(Cell):
         ``Ascend`` ``GPU`` ``CPU``
 
     Examples:
+        >>> import mindspore
+        >>> from mindspore import Tensor, nn
+        >>> import numpy as np
         >>> input = Tensor(np.arange(0, 100).reshape(2, 10, 5), mindspore.float32)
         >>> net = nn.Unflatten(1, (2, 5))
         >>> output = net(input)

mindspore/nn/layer/channel_shuffle.py

@@ -45,35 +45,35 @@ class ChannelShuffle(Cell):
         ``Ascend`` ``GPU`` ``CPU``
 
     Examples:
-        >>> channel_shuffle = nn.ChannelShuffle(2)
-        >>> x = Tensor(np.arange(16).astype(np.int32).reshape(1, 4, 2, 2))
+        >>> import mindspore as ms
+        >>> import numpy as np
+        >>> channel_shuffle = ms.nn.ChannelShuffle(2)
+        >>> x = ms.Tensor(np.arange(16).astype(np.int32).reshape(1, 4, 2, 2))
         >>> print(x)
-        [[[[0 1],
-           [2 3]],
-          [[4 5],
-           [6 7]],
-          [[8 9],
-           [10 11]],
-          [[12 13],
-           [14 15]],
-         ]]
+        [[[[ 0  1]
+           [ 2  3]]
+          [[ 4  5]
+           [ 6  7]]
+          [[ 8  9]
+           [10 11]]
+          [[12 13]
+           [14 15]]]]
         >>> output = channel_shuffle(x)
         >>> print(output)
-        [[[[0 1],
-           [2 3]],
-          [[8 9],
-           [10 11]],
-          [[4 5],
-           [6 7]],
-          [[12 13],
-           [14 15]],
-         ]]
+        [[[[ 0  1]
+           [ 2  3]]
+          [[ 8  9]
+           [10 11]]
+          [[ 4  5]
+           [ 6  7]]
+          [[12 13]
+           [14 15]]]]
     """
     def __init__(self, groups):
         """Initialize ChannelShuffle."""
         super(ChannelShuffle, self).__init__()
         if not isinstance(groups, int):
-            raise TypeError("For ChannelShuffle, the param `groups` must be int, but got {}.".format(type(groups)))
+            raise TypeError(f"For ChannelShuffle, the param `groups` must be int, but got {type(groups)}.")
         if groups < 1:
             raise ValueError(f"For ChannelShuffle, the param `groups` must be larger than 0, but got {groups}.")