From 076af4a21c4cb12cc07933a1c7f7e17997bb3cb1 Mon Sep 17 00:00:00 2001 From: liuyang_655 Date: Mon, 10 Jan 2022 23:31:01 +0800 Subject: [PATCH] modify api note --- .../api_python/mindspore/mindspore.Tensor.rst | 42 +++++----- .../api_python/nn/mindspore.nn.CellList.rst | 42 ++++------ .../nn/mindspore.nn.SequentialCell.rst | 38 +++++++-- mindspore/python/mindspore/common/tensor.py | 6 +- .../python/mindspore/nn/layer/container.py | 78 ++++++++++++------- 5 files changed, 120 insertions(+), 86 deletions(-) diff --git a/docs/api/api_python/mindspore/mindspore.Tensor.rst b/docs/api/api_python/mindspore/mindspore.Tensor.rst index 935a6c34798..3005b0eaf82 100644 --- a/docs/api/api_python/mindspore/mindspore.Tensor.rst +++ b/docs/api/api_python/mindspore/mindspore.Tensor.rst @@ -124,11 +124,11 @@ mindspore.Tensor **返回：** - Tensor，最大值的索引。它具有与此Tensor相同的shape，但移除了轴方向上的维度。 + Tensor，最大值的索引。它与原始Tensor具有相同的shape，但移除了轴方向上的维度。 **异常：** - - **ValueError** - 轴超出了范围。 + - **ValueError** - 入参axis的设定值超出了范围。 **支持平台：** @@ -152,11 +152,11 @@ mindspore.Tensor **返回：** - Tensor，最小Tensor的索引。它与Tensor的shape相同，但移除了轴方向上的维度。 + Tensor，最小Tensor的索引。它与原始Tensor具有相同的shape，但移除了轴方向上的维度。 **异常：** - - **ValueError** - 轴超出了范围。 + - **ValueError** - 入参axis的设定值超出了范围。 **支持平台：** @@ -192,7 +192,7 @@ mindspore.Tensor .. py:method:: astype(dtype, copy=True) - 返回Tensor的副本，并将其转换为指定类型。 + 将Tensor转为指定数据类型，可指定是否返回副本。 **参数：** @@ -222,16 +222,16 @@ mindspore.Tensor .. py:method:: choose(choices, mode='clip') - 通过索引数组和Tensor数组中构造一个Tensor。 + 根据原始Tensor数组和一个索引数组构造一个新的Tensor。 **参数：** - - **choices** (Union[tuple, list, Tensor]) - 选择数组。输入的索引数组和 `choose` 广播维度必须相同。如果 `choices` 本身是一个数组，则其最外层的维度（即，对应于 `choices.shape[0]` 的维度）被用来定义长度。 + - **choices** (Union[tuple, list, Tensor]) - 索引选择数组。原始输入Tensor和 `choices` 的广播维度必须相同。如果 `choices` 本身是一个Tensor，则其最外层的维度（即，对应于第0维的维度）被用来定义 `choices` 数组。 - **mode** ('raise', 'wrap', 'clip', optional) - 指定如何处理 `[0, n-1]` 外部的索引： - **raise** – 引发异常（默认）； - - **wrap** – 绕接； - - **clip** – 裁剪到范围。`clip` 模式意味着所有过大的索引都将替换为在轴方向上寻址最后一个元素的索引。注：这将禁用具有负数的索引。 + - **wrap** – 原值映射为对n取余后的值； + - **clip** – 大于n-1的值会被映射为n-1。该模式下禁用负数索引。 **返回：** @@ -293,7 +293,7 @@ mindspore.Tensor .. py:method:: copy() - 返回复制的Tensor。 + 复制一个Tensor并返回。 .. note:: 当前实现不支持类似NumPy的 `order` 参数。 @@ -326,7 +326,7 @@ mindspore.Tensor **参数：** - - **axis** (int, optional) - 轴，在该轴方向上的累积和。其默认值（None）用来计算扁平轴上的累加和。 + - **axis** (int, optional) - 轴，在该轴方向上的累积和。默认情况下，计算所有元素的累加和。 - **dtype** (`mindspore.dtype`, optional) - 如果未指定参数值，则保持与原始Tensor相同，除非参数值是一个精度小于 `float32` 的整数。在这种情况下，使用 `float32` 。默认值：None。 **异常：** @@ -529,7 +529,8 @@ mindspore.Tensor .. py:method:: init_data(slice_index=None, shape=None, opt_shard_group=None) 获取此Tensor的数据。 - 对于同一个Tensor，只可以调用一次 `init_data` 函数。 + + .. note:: 对于同一个Tensor，只可以调用一次 `init_data` 函数。 **参数：** @@ -557,7 +558,7 @@ mindspore.Tensor .. py:method:: item(index=None) - 使用索引从Tensor中获取值。 + 获取Tensor中指定索引的元素。 .. note:: Tensor.item返回的是Tensor标量，而不是Python标量。 @@ -591,7 +592,7 @@ mindspore.Tensor 将标量插入到Tensor（并将标量转换为Tensor的数据类型）。 - 必须至少有1个参数，并且最后一个参数被定义为项。 + 至少有1个参数，并且最后一个参数被定义为设定值。 Tensor.itemset(\*args)等同于 :math:`Tensor[args] = item` 。 **参数：** @@ -634,7 +635,7 @@ mindspore.Tensor - **axis** (Union[None, int, tuple of ints], optional) - 轴，在该轴方向上进行操作。默认情况下，使用扁平输入。如果该参数为整数元组，则在多个轴上选择最大值，而不是在单个轴或所有轴上进行选择。默认值：None。 - **keepdims** (bool, optional) - 如果这个参数为True，被删去的维度保留在结果中，且维度大小设为1。有了这个选项，结果就可以与输入数组进行正确的广播运算。默认值：False。 - - **initial** (scalar, optional) - 输出元素的最小值。该参数必须设置，才能对空切片进行计算。默认值：None。 + - **initial** (scalar, optional) - 输出元素的最小值。如果对空切片进行计算，则该参数必须设置。默认值：None。 - **where** (bool Tensor, optional) - 一个bool数组，被广播以匹配数组维度和选择包含在降维中的元素。如果传递了一个非默认值，则还必须提供初始值。默认值：True。 **返回：** @@ -692,7 +693,7 @@ mindspore.Tensor - **axis** (Union[None, int, tuple of ints], optional) - 轴，在该轴方向上进行操作。默认情况下，使用扁平输入。如果该参数为整数元组，则在多个轴上选择最小值，而不是在单个轴或所有轴上进行选择。默认值：None。 - **keepdims** (bool, optional) - 如果这个参数为True，被删去的维度保留在结果中，且维度大小设为1。有了这个选项，结果就可以与输入数组进行正确的广播运算。默认值：False。 - - **initial** (scalar, optional) - 输出元素的最大值。该参数必须设置，才能对空切片进行计算。默认值：None。 + - **initial** (scalar, optional) - 输出元素的最大值。如果对空切片进行计算，则该参数必须设置。默认值：None。 - **where** (bool Tensor, optional) - 一个布尔数组，被广播以匹配数组维度和选择包含在降维中的元素。如果传递了一个非默认值，则还必须提供初始值。默认值：True。 **返回：** @@ -729,7 +730,7 @@ mindspore.Tensor .. py:method:: ptp(axis=None, keepdims=False) - 该函数名称是"peak to peak"的缩写。 + 该函数名称是"peak to peak"的缩写。计算沿着axis的最大值与最小值的差值。 .. note:: 不支持NumPy参数 `dtype` 和 `out` 。 @@ -823,7 +824,7 @@ mindspore.Tensor .. py:method:: reshape(*shape) - 不改变数据的情况下，为Tensor提供新的shape。 + 不改变数据的情况下，将Tensor的shape改为输入的新shape。 **参数：** @@ -855,7 +856,7 @@ mindspore.Tensor .. py:method:: resize(*new_shape) - 更改Tensor的shape。 + 将Tensor改为输入的新shape, 并将不足的元素补0。 .. note:: 此方法不更改输入数组的大小，也不返回NumPy中的任何内容，而是返回一个具有输入大小的新Tensor。不支持Numpy参数 `refcheck` 。 @@ -1069,8 +1070,7 @@ mindspore.Tensor - **axis** (int, optional) - 在指定维度上选择值。默认情况下，使用展开的输入数组。默认值：None。 - **mode** ('raise', 'wrap', 'clip', optional) - - edge：填充Tensor的边缘值。 - - raise：引发错误。 + - raise：抛出错误。 - wrap：绕接。 - clip：裁剪到范围。 `clip` 模式意味着所有过大的索引都会被在指定轴方向上指向最后一个元素的索引替换。注：这将禁用具有负数的索引。默认值：`clip` 。 diff --git a/docs/api/api_python/nn/mindspore.nn.CellList.rst b/docs/api/api_python/nn/mindspore.nn.CellList.rst index 74583c5533d..8d4939d878f 100644 --- a/docs/api/api_python/nn/mindspore.nn.CellList.rst +++ b/docs/api/api_python/nn/mindspore.nn.CellList.rst @@ -3,58 +3,50 @@ mindspore.nn.CellList .. py:class:: mindspore.nn.CellList(*args, **kwargs) - 构造Cell列表。 + 构造Cell列表。关于Cell的介绍，可参考 `Cell `_。 + + CellList可以像普通Python列表一样使用，其包含的Cell均已初始化。 - CellList可以像普通Python列表一样使用，支持'__getitem__'、'__setitem__'、'__delitem__'、'__len__'、'__iter__'及'__iadd__'，但包含的Cell都已正确注册，且对所有Cell方法可见。 - **参数：** - - **args** (list，可选) - 仅包含Cell子类的列表。 + + **args** (list，可选) - Cell列表。 **支持平台：** - + ``Ascend`` ``GPU`` ``CPU`` **样例：** + >>> import mindspore.nn as nn + >>> >>> conv = nn.Conv2d(100, 20, 3) >>> bn = nn.BatchNorm2d(20) >>> relu = nn.ReLU() >>> cell_ls = nn.CellList([bn]) >>> cell_ls.insert(0, conv) >>> cell_ls.append(relu) - >>> print(cell_ls) - CellList< - (0): Conv2d - (1): BatchNorm2d - (2): ReLU<> - > - + >>> cell_ls.extend([relu, relu]) + .. py:method:: append(cell) 在列表末尾添加一个Cell。 **参数：** - + **cell** (Cell) - 要添加的Cell。 .. py:method:: extend(cells) - 将Python iterable中的Cell追加到列表的末尾。 + 将cells中的Cell添加到列表末尾。 **参数：** - **cells** (list) - 要追加的Cell子类列表。 + **cells** (list) - 要添加的Cell列表。 **异常：** - - **TypeError** - cells不是Cell子类列表。 - + + **TypeError** - cells中的元素不是Cell。 + .. py:method:: insert(index, cell) 在列表中的给定索引之前插入给定的Cell。 @@ -62,4 +54,4 @@ mindspore.nn.CellList **参数：** - **index** (int) - 给定的列表索引。 - - **cell** (Cell) - 要插入的Cell子类。 \ No newline at end of file + - **cell** (Cell) - 要插入的Cell。 \ No newline at end of file diff --git a/docs/api/api_python/nn/mindspore.nn.SequentialCell.rst b/docs/api/api_python/nn/mindspore.nn.SequentialCell.rst index 157b4e274ff..d1367945ea2 100644 --- a/docs/api/api_python/nn/mindspore.nn.SequentialCell.rst +++ b/docs/api/api_python/nn/mindspore.nn.SequentialCell.rst @@ -3,10 +3,11 @@ mindspore.nn.SequentialCell .. py:class:: mindspore.nn.SequentialCell(*args) - 构造Cell顺序容器。 + 构造Cell顺序容器。关于Cell的介绍，可参考 ``_。 - Cell列表将按照它们在构造函数中传递的顺序添加到其中。 - 或者，也可以传入Cell的有序字典。 + SequentialCell将按照传入List的顺序依次将Cell添加。此外，也支持OrderedDict作为构造器传入。 + + .. note:: SequentialCell 和 torch.nn.ModuleList 是不同的，ModuleList是一个用于存储模块的列表，但SequentialCell中的Cell是以级联方式连接的，不是单纯的存储。 **参数：** @@ -29,7 +30,12 @@ mindspore.nn.SequentialCell ``Ascend`` ``GPU`` ``CPU`` **样例：** - + + >>> from mindspore import Tensor + >>> import mindspore + >>> import mindspore.nn as nn + >>> import numpy as np + >>> >>> conv = nn.Conv2d(3, 2, 3, pad_mode='valid', weight_init="ones") >>> relu = nn.ReLU() >>> seq = nn.SequentialCell([conv, relu]) @@ -40,18 +46,34 @@ mindspore.nn.SequentialCell [27. 27.]] [[27. 27.] [27. 27.]]]] - + >>> from collections import OrderedDict + >>> d = OrderedDict() + >>> d["conv"] = conv + >>> d["relu"] = relu + >>> seq = nn.SequentialCell(d) + >>> x = Tensor(np.ones([1, 3, 4, 4]), dtype=mindspore.float32) + >>> output = seq(x) + >>> print(output) + [[[[27. 27.] + [27. 27.]] + [[27. 27.] + [27. 27.]]]] .. py:method:: append(cell) - 在容器末尾添加一个cell。 + 在容器末尾添加一个Cell。 **参数：** - - **cell** (Cell) - 要添加的cell。 + + **cell** (Cell) - 要添加的Cell。 **样例：** + >>> from mindspore import Tensor + >>> import mindspore + >>> import mindspore.nn as nn + >>> import numpy as np + >>> >>> conv = nn.Conv2d(3, 2, 3, pad_mode='valid', weight_init="ones") >>> bn = nn.BatchNorm2d(2) >>> relu = nn.ReLU() diff --git a/mindspore/python/mindspore/common/tensor.py b/mindspore/python/mindspore/common/tensor.py index f7443a850fb..356031007ff 100644 --- a/mindspore/python/mindspore/common/tensor.py +++ b/mindspore/python/mindspore/common/tensor.py @@ -1379,7 +1379,8 @@ class Tensor(Tensor_): def ptp(self, axis=None, keepdims=False): """ - The name of the function comes from the acronym for "peak to peak". + The name of the function comes from the acronym for "peak to peak". Calculate the difference between the + maximum value and the minimum value along the axis. Note: Numpy argument `out` is not supported. @@ -1490,7 +1491,8 @@ class Tensor(Tensor_): def init_data(self, slice_index=None, shape=None, opt_shard_group=None): """ Get the tensor format data of this Tensor. - The init_data function can be called once for the same tensor. + Note: + The init_data function can be called once for the same tensor. Args: slice_index (int): Slice index of a parameter's slices. diff --git a/mindspore/python/mindspore/nn/layer/container.py b/mindspore/python/mindspore/nn/layer/container.py index 1753684c4a9..0f558fb0853 100644 --- a/mindspore/python/mindspore/nn/layer/container.py +++ b/mindspore/python/mindspore/nn/layer/container.py @@ -78,14 +78,14 @@ def _get_prefix_and_index(cells): class _CellListBase: """ - An interface for base the cell as list. + An interface for base the Cell as list. - The sequential cell may be iterated using the construct method using for-in statement. + The sequential Cell may be iterated using the construct method using for-in statement. But there are some scenarios that the construct method built-in does not fit. For convenience, we provide an interface that indicates the sequential - cell may be interpreted as list of cells, so it can be accessed using - iterator or subscript when a sequential cell instantiate is accessed - by iterator or subscript , it will be interpreted as a list of cells. + Cell may be interpreted as list of Cells, so it can be accessed using + iterator or subscript when a sequential Cell instantiate is accessed + by iterator or subscript, it will be interpreted as a list of Cells. """ def __init__(self): """Initialize _CellListBase.""" @@ -105,13 +105,18 @@ class _CellListBase: class SequentialCell(Cell): """ - Sequential cell container. + Sequential Cell container. For more details about Cell, please refer to + `Cell `_. A list of Cells will be added to it in the order they are passed in the constructor. Alternatively, an ordered dict of cells can also be passed in. + Note: + SequentialCell and torch.nn.ModuleList are different, ModuleList is a list for storing modules. However, + the layers in a Sequential are connected in a cascading way. + Args: - args (list, OrderedDict): List of subclass of Cell. + args (list, OrderedDict): List or OrderedDict of subclass of Cell. Inputs: - **x** (Tensor) - Tensor with shape according to the first Cell in the sequence. @@ -126,6 +131,11 @@ class SequentialCell(Cell): ``Ascend`` ``GPU`` ``CPU`` Examples: + >>> from mindspore import Tensor + >>> import mindspore + >>> import mindspore.nn as nn + >>> import numpy as np + >>> >>> conv = nn.Conv2d(3, 2, 3, pad_mode='valid', weight_init="ones") >>> relu = nn.ReLU() >>> seq = nn.SequentialCell([conv, relu]) @@ -136,6 +146,18 @@ class SequentialCell(Cell): [27. 27.]] [[27. 27.] [27. 27.]]]] + >>> from collections import OrderedDict + >>> d = OrderedDict() + >>> d["conv"] = conv + >>> d["relu"] = relu + >>> seq = nn.SequentialCell(d) + >>> x = Tensor(np.ones([1, 3, 4, 4]), dtype=mindspore.float32) + >>> output = seq(x) + >>> print(output) + [[[[27. 27.] + [27. 27.]] + [[27. 27.] + [27. 27.]]]] """ def __init__(self, *args): """Initialize SequentialCell.""" @@ -218,12 +240,17 @@ class SequentialCell(Cell): def append(self, cell): """ - Appends a given cell to the end of the list. + Appends a given Cell to the end of the list. Args: - cell(Cell): The subcell to be appended. + cell(Cell): The Cell to be appended. Examples: + >>> from mindspore import Tensor + >>> import mindspore + >>> import mindspore.nn as nn + >>> import numpy as np + >>> >>> conv = nn.Conv2d(3, 2, 3, pad_mode='valid', weight_init="ones") >>> bn = nn.BatchNorm2d(2) >>> relu = nn.ReLU() @@ -252,11 +279,10 @@ class SequentialCell(Cell): class CellList(_CellListBase, Cell): """ - Holds Cells in a list. + Holds Cells in a list. For more details about Cell, please refer to + `Cell `_. - CellList can be used like a regular Python list, support - '__getitem__', '__setitem__', '__delitem__', '__len__', '__iter__' and '__iadd__', - but cells it contains are properly registered, and will be visible by all Cell methods. + CellList can be used like a regular Python list, the Cells it contains have been initialized. Args: args (list, optional): List of subclass of Cell. @@ -265,23 +291,15 @@ class CellList(_CellListBase, Cell): ``Ascend`` ``GPU`` ``CPU`` Examples: + >>> import mindspore.nn as nn + >>> >>> conv = nn.Conv2d(100, 20, 3) >>> bn = nn.BatchNorm2d(20) >>> relu = nn.ReLU() >>> cell_ls = nn.CellList([bn]) >>> cell_ls.insert(0, conv) >>> cell_ls.append(relu) - >>> print(cell_ls) - CellList< - (0): Conv2d - (1): BatchNorm2d - (2): ReLU<> - > + >>> cell_ls.extend([relu, relu]) """ def __init__(self, *args, **kwargs): """Initialize CellList.""" @@ -346,11 +364,11 @@ class CellList(_CellListBase, Cell): def insert(self, index, cell): """ - Inserts a given cell before a given index in the list. + Inserts a given Cell before a given index in the list. Args: index(int): The Insert index in the CellList. - cell(Cell): The subcell to be inserted. + cell(Cell): The Cell to be inserted. """ cls_name = self.__class__.__name__ idx = _valid_index(len(self), index, cls_name) @@ -370,13 +388,13 @@ class CellList(_CellListBase, Cell): def extend(self, cells): """ - Appends cells from a Python iterable to the end of the list. + Appends Cells from a Python iterable to the end of the list. Args: - cells(list): The subcells to be extended. + cells(list): The Cells to be extended. Raises: - TypeError: If the cells are not a list of subcells. + TypeError: If the argument cells are not a list of Cells. """ cls_name = self.__class__.__name__ if not isinstance(cells, list): @@ -392,7 +410,7 @@ class CellList(_CellListBase, Cell): def append(self, cell): """ - Appends a given cell to the end of the list. + Appends a given Cell to the end of the list. Args: cell(Cell): The subcell to be appended.