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

mindspore/nn/layer/combined.py

@@ -43,34 +43,35 @@ class Conv2dBnAct(Cell):
             the kernel. A tuple of 2 ints means the first value is for the height and the other is for the
             width of the kernel.
         stride (int): Specifies stride for all spatial dimensions with the same value. The value of stride must be
-            greater than or equal to 1 and lower than any one of the height and width of the `x`. Default: 1.
-        pad_mode (str): Specifies padding mode. The optional values are "same", "valid", "pad". Default: "same".
-        padding (int): Implicit paddings on both sides of the `x`. Default: 0.
+            greater than or equal to 1 and lower than any one of the height and width of the `x`. Default: ``1`` .
+        pad_mode (str): Specifies padding mode. The optional values are ``"same"`` , ``"valid"`` , ``"pad"`` .
+            Default: ``"same"`` .
+        padding (int): Implicit paddings on both sides of the `x`. Default: ``0`` .
         dilation (int): Specifies the dilation rate to use for dilated convolution. If set to be :math:`k > 1`,
             there will be :math:`k - 1` pixels skipped for each sampling location. Its value must be greater than
-            or equal to 1 and lower than any one of the height and width of the `x`. Default: 1.
+            or equal to 1 and lower than any one of the height and width of the `x`. Default: ``1`` .
         group (int): Splits filter into groups, `in_channels` and `out_channels` must be
-            divisible by the number of groups. Default: 1.
-        has_bias (bool): Specifies whether the layer uses a bias vector. Default: False.
+            divisible by the number of groups. Default: ``1`` .
+        has_bias (bool): Specifies whether the layer uses a bias vector. Default: ``False`` .
         weight_init (Union[Tensor, str, Initializer, numbers.Number]): Initializer for the convolution kernel.
             It can be a Tensor, a string, an Initializer or a number. When a string is specified,
-            values from 'TruncatedNormal', 'Normal', 'Uniform', 'HeUniform' and 'XavierUniform' distributions as well
-            as constant 'One' and 'Zero' distributions are possible. Alias 'xavier_uniform', 'he_uniform', 'ones'
-            and 'zeros' are acceptable. Uppercase and lowercase are both acceptable. Refer to the values of
-            Initializer for more details. Default: 'normal'.
+            values from ``'TruncatedNormal'`` , ``'Normal'`` , ``'Uniform'`` , ``'HeUniform'`` and ``'XavierUniform'``
+            distributions as well as constant ``'One'`` and ``'Zero'`` distributions are possible. Alias
+            ``'xavier_uniform'`` , ``'he_uniform'`` , ``'ones'`` and ``'zeros'`` are acceptable. Uppercase and
+            lowercase are both acceptable. Refer to the values of Initializer for more details. Default: ``'normal'`` .
         bias_init (Union[Tensor, str, Initializer, numbers.Number]): Initializer for the bias vector. Possible
             Initializer and string are the same as 'weight_init'. Refer to the values of
-            Initializer for more details. Default: 'zeros'.
-        has_bn (bool): Specifies to used batchnorm or not. Default: False.
-        momentum (float): Momentum for moving average for batchnorm, must be [0, 1]. Default:0.997
+            Initializer for more details. Default: ``'zeros'`` .
+        has_bn (bool): Specifies to used batchnorm or not. Default: ``False`` .
+        momentum (float): Momentum for moving average for batchnorm, must be [0, 1]. Default: ``0.997`` .
         eps (float): Term added to the denominator to improve numerical stability for batchnorm, should be greater
-            than 0. Default: 1e-5.
+            than 0. Default: ``1e-5`` .
         activation (Union[str, Cell, Primitive]): Specifies activation type. The optional values are as following:
             'softmax', 'logsoftmax', 'relu', 'relu6', 'tanh', 'gelu', 'sigmoid',
-            'prelu', 'leakyrelu', 'hswish', 'hsigmoid'. Default: None.
-        alpha (float): Slope of the activation function at x < 0 for LeakyReLU. Default: 0.2.
+            'prelu', 'leakyrelu', 'hswish', 'hsigmoid'. Default: ``None`` .
+        alpha (float): Slope of the activation function at x < 0 for LeakyReLU. Default: ``0.2`` .
         after_fake(bool): Determine whether there must be a fake quantization operation after Cond2dBnAct.
-            Default: True.
+            Default: ``True`` .
 
     Inputs:
         - **x** (Tensor) - Tensor of shape :math:`(N, C_{in}, H_{in}, W_{in})`. The data type is float32.
@@ -88,6 +89,9 @@ class Conv2dBnAct(Cell):
         ``Ascend`` ``GPU`` ``CPU``
 
     Examples:
+        >>> import mindspore
+        >>> from mindspore import Tensor, nn
+        >>> import numpy as np
         >>> net = nn.Conv2dBnAct(120, 240, 4, has_bn=True, activation='relu')
         >>> x = Tensor(np.ones([1, 120, 1024, 640]), mindspore.float32)
         >>> result = net(x)
@@ -160,20 +164,20 @@ class DenseBnAct(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: ``'normal'`` .
         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. Default: True.
-        has_bn (bool): Specifies to use batchnorm or not. Default: False.
-        momentum (float): Momentum for moving average for batchnorm, must be [0, 1]. Default:0.9
+            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. Default: ``True`` .
+        has_bn (bool): Specifies to use batchnorm or not. Default: ``False`` .
+        momentum (float): Momentum for moving average for batchnorm, must be [0, 1]. Default: ``0.9`` .
         eps (float): Term added to the denominator to improve numerical stability for batchnorm, should be greater
-            than 0. Default: 1e-5.
+            than 0. Default: ``1e-5`` .
         activation (Union[str, Cell, Primitive]): Specifies activation type. The optional values are as following:
             'softmax', 'logsoftmax', 'relu', 'relu6', 'tanh', 'gelu', 'sigmoid',
-            'prelu', 'leakyrelu', 'hswish', 'hsigmoid'. Default: None.
-        alpha (float): Slope of the activation function at x < 0 for LeakyReLU. Default: 0.2.
+            'prelu', 'leakyrelu', 'hswish', 'hsigmoid'. Default:  ``None`` .
+        alpha (float): Slope of the activation function at x < 0 for LeakyReLU. Default: ``0.2`` .
         after_fake(bool): Determine whether there must be a fake quantization operation after DenseBnAct.
-            Default: True.
+            Default: ``True`` .
 
     Inputs:
         - **x** (Tensor) - Tensor of shape :math:`(N, in\_channels)`. The data type is float32.
@@ -191,6 +195,9 @@ class DenseBnAct(Cell):
         ``Ascend`` ``GPU`` ``CPU``
 
     Examples:
+        >>> import mindspore
+        >>> from mindspore import Tensor, nn
+        >>> import numpy as np
         >>> net = nn.DenseBnAct(3, 4)
         >>> x = Tensor(np.random.randint(0, 255, [2, 3]), mindspore.float32)
         >>> result = net(x)

mindspore/nn/layer/container.py

@@ -15,12 +15,12 @@
 """container"""
 from __future__ import absolute_import
 
-from collections import OrderedDict
+from collections import OrderedDict, abc
 from abc import abstractmethod
 
 from mindspore.nn.cell import Cell
 
-__all__ = ['SequentialCell', 'CellList']
+__all__ = ['SequentialCell', 'CellList', 'CellDict']
 
 
 def _valid_index(cell_num, index, op_name=None):
@@ -34,6 +34,20 @@ def _valid_index(cell_num, index, op_name=None):
     return index % cell_num
 
 
+def _valid_index_for_inserting(cell_num, index, op_name=None):
+    """
+    Internal function, used to detect the value and type of index for inserting Cell in
+    SequentialCell or CellList.
+    """
+    msg_prefix = f"For '{op_name}', the" if op_name else "The"
+    if not isinstance(index, int):
+        raise TypeError(f"{msg_prefix} type of 'index' must be int, but got {type(index).__name__}.")
+    if not -cell_num <= index <= cell_num:
+        raise IndexError(f"{msg_prefix} value of 'index' must be a number in range [{-cell_num}, {cell_num}], "
+                         f"but got {index}.")
+    return index % cell_num if (cell_num != 0 and index != cell_num) else index
+
+
 def _valid_cell(cell, op_name=None):
     """Internal function, used to check whether the input cell is a subclass of Cell."""
     if issubclass(cell.__class__, Cell):
@@ -109,15 +123,11 @@ class _CellListBase:
 class SequentialCell(Cell):
     """
     Sequential Cell container. For more details about Cell, please refer to
-    `Cell <https://www.mindspore.cn/docs/en/r2.0/api_python/nn/mindspore.nn.Cell.html#mindspore.nn.Cell>`_.
+    `Cell <https://www.mindspore.cn/docs/en/r2.2/api_python/nn/mindspore.nn.Cell.html#mindspore.nn.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 or OrderedDict of subclass of Cell.
 
@@ -134,9 +144,8 @@ class SequentialCell(Cell):
         ``Ascend`` ``GPU`` ``CPU``
 
     Examples:
-        >>> from mindspore import Tensor
         >>> import mindspore
-        >>> import mindspore.nn as nn
+        >>> from mindspore import Tensor, nn
         >>> import numpy as np
         >>>
         >>> conv = nn.Conv2d(3, 2, 3, pad_mode='valid', weight_init="ones")
@@ -257,9 +266,8 @@ class SequentialCell(Cell):
             cell(Cell): The Cell to be appended.
 
         Examples:
-            >>> from mindspore import Tensor
             >>> import mindspore
-            >>> import mindspore.nn as nn
+            >>> from mindspore import Tensor, nn
             >>> import numpy as np
             >>>
             >>> conv = nn.Conv2d(3, 2, 3, pad_mode='valid', weight_init="ones")
@@ -296,7 +304,7 @@ class SequentialCell(Cell):
             cell(Cell): The Cell to be inserted.
         """
         cls_name = self.__class__.__name__
-        idx = _valid_index(len(self), index, cls_name)
+        idx = _valid_index_for_inserting(len(self), index, cls_name)
         _valid_cell(cell, cls_name)
         length = len(self)
         prefix, key_index = _get_prefix_and_index(self._cells)
@@ -317,10 +325,11 @@ class SequentialCell(Cell):
 class CellList(_CellListBase, Cell):
     """
     Holds Cells in a list. For more details about Cell, please refer to
-    `Cell <https://www.mindspore.cn/docs/en/r2.0/api_python/nn/mindspore.nn.Cell.html#mindspore.nn.Cell>`_.
+    `Cell <https://www.mindspore.cn/docs/en/r2.2/api_python/nn/mindspore.nn.Cell.html#mindspore.nn.Cell>`_.
 
-    CellList can be used like a regular Python list, the Cells it contains have been initialized. Unlike the
-    SequentialCell, the cells in CellList are not connected.
+    CellList can be used like a regular Python list, the Cells it contains have been initialized and
+    the types of Cells it contains can not be CellDict.
+    Unlike the SequentialCell, the cells in CellList are not connected.
 
     Args:
         args (list, optional): List of subclass of Cell.
@@ -329,14 +338,13 @@ class CellList(_CellListBase, Cell):
         ``Ascend`` ``GPU`` ``CPU``
 
     Examples:
-        >>> import mindspore.nn as nn
         >>> import mindspore as ms
         >>> import numpy as np
         >>>
-        >>> conv = nn.Conv2d(100, 20, 3)
-        >>> bn = nn.BatchNorm2d(20)
-        >>> relu = nn.ReLU()
-        >>> cell_ls = nn.CellList([bn])
+        >>> conv = ms.nn.Conv2d(100, 20, 3)
+        >>> bn = ms.nn.BatchNorm2d(20)
+        >>> relu = ms.nn.ReLU()
+        >>> cell_ls = ms.nn.CellList([bn])
         >>> cell_ls.insert(0, conv)
         >>> cell_ls.append(relu)
         >>> cell_ls.extend([relu, relu])
@@ -420,7 +428,7 @@ class CellList(_CellListBase, Cell):
             cell(Cell): The Cell to be inserted.
         """
         cls_name = self.__class__.__name__
-        idx = _valid_index(len(self), index, cls_name)
+        idx = _valid_index_for_inserting(len(self), index, cls_name)
         _valid_cell(cell, cls_name)
         length = len(self)
         prefix, key_index = _get_prefix_and_index(self._cells)
@@ -440,7 +448,7 @@ class CellList(_CellListBase, Cell):
         Appends Cells from a Python iterable to the end of the list.
 
         Args:
-            cells(list): The Cells to be extended.
+            cells(list): The Cells to be extended, the types of Cells can not be CellDict.
 
         Raises:
             TypeError: If the argument cells are not a list of Cells.
@@ -451,6 +459,9 @@ class CellList(_CellListBase, Cell):
                             f"should be instance of list, but got {type(cells).__name__}.")
         prefix, _ = _get_prefix_and_index(self._cells)
         for cell in cells:
+            if isinstance(cell, CellDict):
+                raise TypeError(f"For '{cls_name}', the type of cell can not be CellDict, "
+                                f"but got {type(cell).__name__}.")
             if _valid_cell(cell, cls_name):
                 if self._auto_prefix:
                     cell.update_parameters_name(prefix + str(len(self)) + ".")
@@ -477,3 +488,247 @@ class CellList(_CellListBase, Cell):
 
     def construct(self, *inputs):
         raise NotImplementedError
+
+
+class _CellDictBase:
+    """
+    An interface for base the Cell as dict.
+
+    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 dict of Cells, so it can be accessed using
+    key when a sequential Cell instantiate is accessed by key,
+    it will be interpreted as a dict of Cells.
+    """
+    def __init__(self):
+        """Initialize _CellDictBase."""
+        self.__cell_as_dict__ = True
+
+    @abstractmethod
+    def __len__(self):
+        pass
+
+    @abstractmethod
+    def __getitem__(self, index):
+        pass
+
+    def construct(self):
+        raise NotImplementedError
+
+
+class CellDict(_CellDictBase, Cell):
+    """
+    Holds Cells in a dictionary. For more details about `Cell` , please refer to :class:`mindspore.nn.Cell` .
+
+    `CellDict` can be used like a regular Python dictionary.
+
+    Args:
+        args (iterable, optional): An iterable of key-value pairs of (key, Cell), the type of key-value pairs is
+                                   (string, Cell); Or a mapping(dictionary) from string to Cell.
+                                   The type of Cell can not be CellDict, CellList or SequentialCell.
+                                   The key can not be same with the attributes of class Cell, can not contain '.',
+                                   can not be an empty string.
+                                   The key of type string is used to search corresponding Cell in the CellDict.
+        kwargs (dict): Reserved for keyword argument to be expanded.
+
+    Supported Platforms:
+        ``Ascend`` ``GPU`` ``CPU``
+
+    Examples:
+        >>> import collections
+        >>> from collections import OrderedDict
+        >>> import mindspore as ms
+        >>> import numpy as np
+        >>> from mindspore import Tensor, nn
+        >>>
+        >>> cell_dict = nn.CellDict({'conv': nn.Conv2d(10, 6, 5),
+        ...                          'relu': nn.ReLU(),
+        ...                          'max_pool2d': nn.MaxPool2d(kernel_size=4, stride=4)})
+        >>> print(len(cell_dict))
+        3
+        >>> cell_dict.clear()
+        >>> print(len(cell_dict))
+        0
+        >>> ordered_cells = OrderedDict([('conv', nn.Conv2d(10, 6, 5, pad_mode='valid')),
+        ...                              ('relu', nn.ReLU()),
+        ...                              ('max_pool2d', nn.MaxPool2d(kernel_size=2, stride=2))])
+        >>> cell_dict.update(ordered_cells)
+        >>> x = Tensor(np.ones([1, 10, 6, 10]), ms.float32)
+        >>> for cell in cell_dict.values():
+        ...     x = cell(x)
+        >>> print(x.shape)
+        (1, 6, 1, 3)
+        >>> x = Tensor(np.ones([1, 10, 6, 10]), ms.float32)
+        >>> for item in cell_dict.items():
+        ...     x = item[1](x)
+        >>> print(x.shape)
+        (1, 6, 1, 3)
+        >>> print(cell_dict.keys())
+        odict_keys(['conv', 'relu', 'max_pool2d'])
+        >>> pop_cell = cell_dict.pop('conv')
+        >>> x = Tensor(np.ones([1, 10, 6, 5]), ms.float32)
+        >>> x = pop_cell(x)
+        >>> print(x.shape)
+        (1, 6, 2, 1)
+        >>> print(len(cell_dict))
+        2
+    """
+    def __init__(self, *args, **kwargs):
+        """Initialize CellDict."""
+        auto_prefix = kwargs["auto_preifx"] if "auto_prefix" in kwargs.keys() else True
+        _CellDictBase.__init__(self)
+        Cell.__init__(self, auto_prefix)
+        if len(args) == 1:
+            self.update(args[0])
+
+    def __getitem__(self, key):
+        return self._cells[key]
+
+    def __setitem__(self, key, cell):
+        self._validate_key(key)
+        self._validate_cell_type(cell)
+        self._update_cell_para_name(key, cell)
+        self._cells[key] = cell
+
+    def __delitem__(self, key):
+        del self._cells[key]
+
+    def __len__(self):
+        return len(self._cells)
+
+    def __iter__(self):
+        return iter(self._cells)
+
+    def __contains__(self, key):
+        return key in self._cells
+
+    def _validate_key(self, key):
+        """validate key."""
+        cls_name = self.__class__.__name__
+        if not isinstance(key, str):
+            raise TypeError(f"For '{cls_name}', the type of key should be string "
+                            f"but got {type(key).__name__}.")
+        if hasattr(self, key) and key not in self._cells:
+            raise KeyError(f"For '{cls_name}', the key can not be same with the attributes of Cell, "
+                           f"but got key {key}.")
+        if '.' in key:
+            raise KeyError(f"For '{cls_name}', key can not contain \".\", "
+                           f"but got key {key}")
+        if key == '':
+            raise KeyError(f"For '{cls_name}', key can not be empty string \"\", "
+                           f"but got key {key}")
+
+    def _validate_cell_type(self, cell):
+        """validate cell type."""
+        cls_name = self.__class__.__name__
+        if cell is None:
+            raise TypeError(f"For '{cls_name}', cell can not be None.")
+        if not isinstance(cell, Cell):
+            raise TypeError(f"For '{cls_name}', the type of cell should be Cell, "
+                            f"but got {type(cell).__name__}.")
+        if isinstance(cell, (CellDict, CellList, SequentialCell)):
+            raise TypeError(f"For '{cls_name}', the type of cell can not be CellDict, CellList or SequentialCell, "
+                            f"but got {type(cell).__name__}.")
+
+    def _update_cell_para_name(self, key, cell):
+        """update cell para name."""
+        if self._auto_prefix:
+            prefix, _ = _get_prefix_and_index(self._cells)
+            cell.update_parameters_name(prefix + key + ".")
+
+    def clear(self):
+        """
+        Remove all Cells from the CellDict.
+        """
+        return self._cells.clear()
+
+    def pop(self, key):
+        """
+        Remove key from the CellDict and return its cell.
+
+        Args:
+            key (string): key to pop from the CellDict.
+
+        Raises:
+            KeyError: If `key` not exist in CellDict when attempt to access cell.
+        """
+        value = self[key]
+        del self[key]
+        return value
+
+    def keys(self):
+        """
+        Return an iterable of the CellDict keys.
+
+        Returns:
+            An iterable object.
+        """
+        return self._cells.keys()
+
+    def values(self):
+        """
+        Return an iterable of the CellDict values.
+
+        Returns:
+            An iterable object.
+        """
+        return self._cells.values()
+
+    def items(self):
+        """
+        Return an iterable of the CellDict key-value pairs.
+
+        Returns:
+            An iterable object.
+        """
+        return self._cells.items()
+
+    def update(self, cells):
+        """
+        Update the CellDict by overwriting the existing keys with the key-value pairs from a mapping or an iterable.
+
+        Args:
+            cells (iterable): An iterable of key-value pairs of (key, Cell), the type of key-value pairs is
+                              (string, Cell); Or a mapping(dictionary) from string to Cell.
+                              The type of Cell can not be CellDict, CellList or SequentialCell.
+                              The key can not be same with the attributes of class Cell, can not contain '.',
+                              can not be an empty string.
+
+        Note:
+            If the `cells` is a CellDict, an OrderedDict or an iterable containing key-value pairs,
+            the order of newly added elements is maintained.
+
+        Raises:
+            TypeError: If `cells` is not an iterable object.
+            TypeError: If key-value pairs in `cells` are not iterable objects.
+            ValueError: If the length of key-value pairs in `cells` is not 2.
+            TypeError: If the cell in `cells` is None.
+            TypeError: If the type of cell in `cells` is not Cell.
+            TypeError: If the type of cell in `cells` is CellDict, CellList or SequentialCell.
+            TypeError: If the type of key in `cells` is not string.
+            KeyError: If the key in `cells` is same with the attributes of class Cell.
+            KeyError: If the key in `cells` contain ".".
+            KeyError: If the key in `cells` is an empty string.
+        """
+        if not isinstance(cells, abc.Iterable):
+            raise TypeError("CellDict.update() should be called with an "
+                            "iterable of key-value pairs, but got " +
+                            type(cells).__name__)
+        if isinstance(cells, (OrderedDict, CellDict, abc.Mapping)):
+            for key, cell in cells.items():
+                self[key] = cell
+        else:
+            for id, k_v in enumerate(cells):
+                if not isinstance(k_v, abc.Iterable):
+                    raise TypeError("CellDict update sequence element "
+                                    "#" + str(id) + " should be Iterable; but got " +
+                                    type(k_v).__name__)
+                if len(k_v) != 2:
+                    raise ValueError("CellDict update sequence element "
+                                     "#" + str(id) + ", length should be 2; but has length " +
+                                     str(len(k_v)))
+                self[k_v[0]] = k_v[1]
+
+    def construct(self, *inputs):
+        raise NotImplementedError