mindspore 2.2.11__cp37-cp37m-manylinux1_x86_64.whl → 2.3.0rc1__cp37-cp37m-manylinux1_x86_64.whl

mindspore/common/sparse_tensor.py

@@ -226,7 +226,7 @@ class COOTensor(COOTensor_):
 
     Common arithmetic operations include: addition (+), subtraction (-), multiplication (*),
     and division (/). For details about operations supported by `COOTensor`, see
-    `operators <https://www.mindspore.cn/docs/en/r2.2/note/static_graph_syntax_support.html#operators>`_.
+    `operators <https://www.mindspore.cn/docs/en/r2.3.q1/note/static_graph_syntax_support.html#operators>`_.
 
     .. warning::
         - This is an experimental API that is subject to change or deletion.
@@ -240,7 +240,7 @@ class COOTensor(COOTensor_):
             Please make sure that the indices are in range of the given shape.
         values (Tensor): A 1-D tensor of any type and shape :math:`(N)`, which
             supplies the values for each element in `indices`. Default: ``None`` .
-        shape (tuple(int)): An integer tuple of size `ndims`,
+        shape (tuple(int)): An integer tuple of shape :math:`(ndims)`,
             which specifies the dense_shape of the sparse tensor. Default: ``None`` .
         coo_tensor (COOTensor): A COOTensor object. Default: ``None`` .
 
@@ -351,22 +351,69 @@ class COOTensor(COOTensor_):
 
     @property
     def dtype(self) -> mstype:
-        """Return the dtype of the values of COOTensor (:class:`mindspore.dtype`)."""
+        """
+        Return the dtype of the values of COOTensor (:class:`mindspore.dtype`).
+
+        Examples:
+            >>> import mindspore as ms
+            >>> from mindspore import Tensor, COOTensor
+            >>> indices = Tensor([[0, 1], [1, 2]], dtype=ms.int32)
+            >>> values = Tensor([1, 2], dtype=ms.float32)
+            >>> shape = (3, 4)
+            >>> coo_tensor = COOTensor(indices, values, shape)
+            >>> print(coo_tensor.dtype)
+            Float32
+        """
         return self._dtype
 
     @property
     def size(self) -> int:
-        """Return the number of non-zero values."""
+        """
+        Return the number of non-zero values.
+
+        Examples:
+            >>> import mindspore as ms
+            >>> from mindspore import Tensor, COOTensor
+            >>> indices = Tensor([[0, 1, 2], [1, 0, 2]], dtype=ms.int32)
+            >>> values = Tensor([1, 5, 4], dtype=ms.float32)
+            >>> shape = (3, 3)
+            >>> coo_tensor = COOTensor(indices.transpose(), values, shape)
+            >>> print(coo_tensor.size)
+            3
+        """
         return self.values.size
 
     @property
     def itemsize(self) -> int:
-        """Return the length of one tensor element in bytes."""
+        """
+        Return the length of one tensor element in bytes.
+
+        Examples:
+            >>> import mindspore as ms
+            >>> from mindspore import Tensor, COOTensor
+            >>> indices = Tensor([[0, 1], [1, 2]], dtype=ms.int32)
+            >>> values = Tensor([1, 2], dtype=ms.float64)
+            >>> shape = (3, 4)
+            >>> coo_tensor = COOTensor(indices, values, shape)
+            >>> print(coo_tensor.itemsize)
+            8
+        """
         return self.values.itemsize
 
     @property
     def ndim(self) -> int:
-        """Return the number of tensor dimensions."""
+        """
+        Return the number of tensor dimensions.
+
+        Examples:
+            >>> import mindspore as ms
+            >>> from mindspore import Tensor, COOTensor
+            >>> indices = Tensor([[0, 1], [1, 2]], dtype=ms.int32)
+            >>> values = Tensor([1, 2], dtype=ms.float32)
+            >>> coo_tensor = COOTensor(indices, values, (3, 4))
+            >>> print(coo_tensor.ndim)
+            2
+        """
         return len(self.shape)
 
     def coalesce(self) -> COOTensor:
@@ -408,6 +455,17 @@ class COOTensor(COOTensor_):
 
         Supported Platforms:
             ``GPU`` ``CPU``
+
+        Examples:
+            >>> import mindspore as ms
+            >>> from mindspore import Tensor, COOTensor
+            >>> indices = Tensor([[0, 1], [1, 2]], dtype=ms.int32)
+            >>> values = Tensor([1, 2], dtype=ms.int32)
+            >>> shape = (3, 4)
+            >>> coo_tensor = COOTensor(indices, values, shape)
+            >>> print(coo_tensor.to_csr())
+            CSRTensor(shape=[3, 4], dtype=Int32, indptr=Tensor(shape=[4], dtype=Int32, value=[0 1 2 2]),
+                indices=Tensor(shape=[2], dtype=Int32, value=[1 2]), values=Tensor(shape=[2], dtype=Int32, value=[1 2]))
         """
         row_indices = self.indices[:, 0]
         col_indices = self.indices[:, 1]
@@ -429,6 +487,18 @@ class COOTensor(COOTensor_):
 
         Supported Platforms:
             ``GPU``
+
+        Examples:
+            >>> import mindspore as ms
+            >>> from mindspore import Tensor, COOTensor
+            >>> indices = Tensor([[0, 1, 2], [1, 0, 2]], dtype=ms.int32)
+            >>> values = Tensor([1, 5, 4], dtype=ms.float32)
+            >>> shape = (3, 3)
+            >>> coo_tensor = COOTensor(indices.transpose(), values, shape)
+            >>> print(coo_tensor.to_dense())
+            [[0. 1. 0.]
+             [5. 0. 0.]
+             [0. 0. 4.]]
         """
         zeros_tensor = tensor_operator_registry.get("zeros")(self.shape, self.values.dtype)
         return tensor_operator_registry.get("tensor_scatter_add")(
@@ -469,6 +539,18 @@ class COOTensor(COOTensor_):
 
         Supported Platforms:
             ``Ascend`` ``GPU`` ``CPU``
+
+        Examples:
+            >>> import mindspore as ms
+            >>> from mindspore import Tensor, COOTensor
+            >>> indices = Tensor([[0, 1], [1, 2]], dtype=ms.int32)
+            >>> values = Tensor([1, 2], dtype=ms.float32)
+            >>> shape = (3, 4)
+            >>> coo_tensor = COOTensor(indices, values, shape)
+            >>> print(coo_tensor.to_tuple())
+            (Tensor(shape=[2, 2], dtype=Int32, value=
+            [[0, 1],
+             [1, 2]]), Tensor(shape=[2], dtype=Float32, value= [ 1.00000000e+00,  2.00000000e+00]), (3, 4))
         """
         return self.indices, self.values, self.shape
 
@@ -481,6 +563,17 @@ class COOTensor(COOTensor_):
 
         Supported Platforms:
             ``Ascend`` ``GPU`` ``CPU``
+
+        Examples:
+            >>> import mindspore as ms
+            >>> from mindspore import Tensor, COOTensor
+            >>> indices = Tensor([[0, 1, 2], [1, 0, 2]], dtype=ms.int32)
+            >>> values = Tensor([1, -5, -4], dtype=ms.float32)
+            >>> shape = (3, 3)
+            >>> coo_tensor = COOTensor(indices.transpose(), values, shape)
+            >>> res = coo_tensor.abs()
+            >>> print(res.values)
+            [1. 5. 4.]
         """
         data = self.values.abs()
         return COOTensor(self.indices, data, self.shape)
@@ -544,7 +637,7 @@ class COOTensor(COOTensor_):
 
 
 class CSRTensor(CSRTensor_):
-    """
+    r"""
     Constructs a sparse tensor in CSR (Compressed Sparse Row) format, with specified
     values indicated by `values` and row and column positions indicated by `indptr`
     and `indices`.
@@ -560,12 +653,12 @@ class CSRTensor(CSRTensor_):
 
     Common arithmetic operations include: addition (+), subtraction (-), multiplication (*),
     and division (/). For details about operations supported by `CSRTensor`, see
-    `operators <https://www.mindspore.cn/docs/en/r2.2/note/static_graph_syntax_support.html#operators>`_.
+    `operators <https://www.mindspore.cn/docs/en/r2.3.q1/note/static_graph_syntax_support.html#operators>`_.
 
     .. warning::
         - This is an experimental API that is subjected to change.
         - If the values given by `indptr` or `indices` are invalid, the results may be undefined. Invalid values include
-          when the length of `values` or `indices` exceeds the range indicated by indptr, and when the columns
+          when the length of `values` or `indices` exceeds the range indicated by `indptr`, and when the columns
           indicated by `indices` are repeated on the same row.
 
     Args:
@@ -577,10 +670,10 @@ class CSRTensor(CSRTensor_):
             must be int16, int32 or int64.
         values (Tensor): Tensor, which has the same length as `indices` (values.shape[0] == indices.shape[0]).
             `values`  stores the data for CSRTensor. Default: ``None``.
-        shape (tuple(int)): A tuple indicates the shape of the CSRTensor, and `shape[0]` must equal to `M - 1`,
+        shape (tuple(int)): An integer tuple of shape :math:`(ndims)`, and `shape[0]` must equal to `M - 1`,
             which all equal to number of rows of the CSRTensor. Default: ``None``.
         csr_tensor (CSRTensor): A CSRTensor object.  Values' feature dimension should match with
-            CSRTensor's feature dimension (values.shape[1:] == csr_tensor.shape[2:]). Default: ``None``.
+            CSRTensor's feature dimension :math:`(values.shape[1:] == csr\_tensor.shape[2:])` . Default: ``None``.
 
     Outputs:
         CSRTensor, with shape defined by `shape`, and dtype inferred from `value`.
@@ -668,37 +761,128 @@ class CSRTensor(CSRTensor_):
 
     @property
     def indices(self) -> Tensor:
-        """Return CSRTensor's column indices."""
+        """
+        Return CSRTensor's column indices.
+
+        Examples:
+            >>> import mindspore as ms
+            >>> from mindspore import Tensor, CSRTensor
+            >>> indptr = Tensor([0, 1, 2], dtype=ms.int32)
+            >>> indices = Tensor([0, 1], dtype=ms.int32)
+            >>> values = Tensor([1, 2], dtype=ms.float32)
+            >>> shape = (2, 4)
+            >>> csr_tensor = CSRTensor(indptr, indices, values, shape)
+            >>> print(csr_tensor.indices)
+            [0 1]
+        """
         return Tensor(self._indices)
 
     @property
     def values(self) -> Tensor:
-        """Return CSRTensor's non-zero values."""
+        """
+        Return CSRTensor's non-zero values.
+
+        Examples:
+            >>> import mindspore as ms
+            >>> from mindspore import Tensor, CSRTensor
+            >>> indptr = Tensor([0, 1, 2], dtype=ms.int32)
+            >>> indices = Tensor([0, 1], dtype=ms.int32)
+            >>> values = Tensor([1, 2], dtype=ms.float32)
+            >>> shape = (2, 4)
+            >>> csr_tensor = CSRTensor(indptr, indices, values, shape)
+            >>> print(csr_tensor.values)
+            [1. 2.]
+        """
         return Tensor(self._values)
 
     @property
     def shape(self) -> Tuple[int, ...]:
-        """Return CSRTensor's shape."""
+        """
+        Return CSRTensor's shape.
+
+        Examples:
+            >>> import mindspore as ms
+            >>> from mindspore import Tensor, CSRTensor
+            >>> indptr = Tensor([0, 1, 2], dtype=ms.int32)
+            >>> indices = Tensor([0, 1], dtype=ms.int32)
+            >>> values = Tensor([1, 2], dtype=ms.float32)
+            >>> shape = (2, 4)
+            >>> csr_tensor = CSRTensor(indptr, indices, values, shape)
+            >>> print(csr_tensor.shape)
+            (2, 4)
+        """
         return self._shape
 
     @property
     def dtype(self) -> mstype:
-        """Return the dtype of the values of CSRTensor (:class:`mindspore.dtype`)."""
+        """
+        Return the dtype of the values of CSRTensor (:class:`mindspore.dtype`).
+
+        Examples:
+            >>> import mindspore as ms
+            >>> from mindspore import Tensor, CSRTensor
+            >>> indptr = Tensor([0, 1, 2], dtype=ms.int32)
+            >>> indices = Tensor([0, 1], dtype=ms.int32)
+            >>> values = Tensor([1, 2], dtype=ms.float32)
+            >>> shape = (2, 4)
+            >>> csr_tensor = CSRTensor(indptr, indices, values, shape)
+            >>> print(csr_tensor.dtype)
+            Float32
+        """
         return self._dtype
 
     @property
     def size(self) -> int:
-        """Return the number of non-zero values."""
+        """
+        Return the number of non-zero values.
+
+        Examples:
+            >>> import mindspore as ms
+            >>> from mindspore import Tensor, CSRTensor
+            >>> indptr = Tensor([0, 1, 2], dtype=ms.int32)
+            >>> indices = Tensor([0, 1], dtype=ms.int32)
+            >>> values = Tensor([1, 2], dtype=ms.float32)
+            >>> shape = (2, 4)
+            >>> csr_tensor = CSRTensor(indptr, indices, values, shape)
+            >>> print(csr_tensor.size)
+            2
+        """
         return self.values.size
 
     @property
     def itemsize(self) -> int:
-        """Return the length of one tensor element in bytes."""
+        """
+        Return the length of one tensor element in bytes.
+
+        Examples:
+            >>> import mindspore as ms
+            >>> from mindspore import Tensor, CSRTensor
+            >>> indptr = Tensor([0, 1, 2], dtype=ms.int32)
+            >>> indices = Tensor([0, 1], dtype=ms.int32)
+            >>> values = Tensor([1, 2], dtype=ms.float64)
+            >>> shape = (2, 4)
+            >>> csr_tensor = CSRTensor(indptr, indices, values, shape)
+            >>> print(csr_tensor.itemsize)
+            8
+        """
         return self.values.itemsize
 
     @property
     def ndim(self) -> int:
-        """Return the number of tensor dimensions."""
+        """
+        Return the number of tensor dimensions.
+
+        Examples:
+            >>> import mindspore as ms
+            >>> from mindspore import Tensor, CSRTensor
+            >>> indptr = Tensor([0, 1, 2], dtype=ms.int32)
+            >>> indices = Tensor([0, 1], dtype=ms.int32)
+            >>> values = Tensor([1, 2], dtype=ms.float32)
+            >>> shape = (2, 4)
+            >>> csr_tensor = CSRTensor(indptr, indices, values, shape)
+            >>> print(csr_tensor.ndim)
+            2
+        """
         return len(self.shape)
 
     def to_tuple(self) -> Tuple[Tensor, Tensor, Tensor, Tuple[int, ...]]:
@@ -710,6 +894,19 @@ class CSRTensor(CSRTensor_):
 
         Supported Platforms:
             ``Ascend`` ``GPU`` ``CPU``
+
+        Examples:
+            >>> import mindspore as ms
+            >>> from mindspore import Tensor, CSRTensor
+            >>> indptr = Tensor([0, 1, 2], dtype=ms.int32)
+            >>> indices = Tensor([0, 1], dtype=ms.int32)
+            >>> values = Tensor([1, 2], dtype=ms.float32)
+            >>> shape = (2, 4)
+            >>> csr_tensor = CSRTensor(indptr, indices, values, shape)
+            >>> print(csr_tensor.to_tuple())
+            (Tensor(shape=[3], dtype=Int32, value= [0, 1, 2]), Tensor(shape=[2], dtype=Int32, value= [0, 1]),
+                Tensor(shape=[2], dtype=Float32, value= [ 1.00000000e+00,  2.00000000e+00]), (2, 4))
+
         """
         return self.indptr, self.indices, self.values, self.shape
 
@@ -725,6 +922,19 @@ class CSRTensor(CSRTensor_):
 
         Supported Platforms:
             ``GPU`` ``CPU``
+
+        Examples:
+            >>> import mindspore as ms
+            >>> from mindspore import Tensor, CSRTensor
+            >>> indptr = Tensor([0, 1, 2], dtype=ms.int32)
+            >>> indices = Tensor([0, 1], dtype=ms.int32)
+            >>> values = Tensor([1, 2], dtype=ms.int32)
+            >>> shape = (2, 4)
+            >>> csr_tensor = CSRTensor(indptr, indices, values, shape)
+            >>> print(csr_tensor.to_coo())
+            COOTensor(shape=[2, 4], dtype=Int32, indices=Tensor(shape=[2, 2], dtype=Int32, value=
+            [[0 0]
+             [1 1]]), values=Tensor(shape=[2], dtype=Int32, value=[1 2]))
         """
         if self.ndim != 2:
             raise ValueError("Currently only support 2-D CSRTensor when converting to COOTensor.")
@@ -741,6 +951,18 @@ class CSRTensor(CSRTensor_):
 
         Supported Platforms:
             ``GPU``
+
+        Examples:
+            >>> import mindspore as ms
+            >>> from mindspore import Tensor, CSRTensor
+            >>> indptr = Tensor([0, 1, 2], dtype=ms.int32)
+            >>> indices = Tensor([0, 1], dtype=ms.int32)
+            >>> values = Tensor([1, 2], dtype=ms.float32)
+            >>> shape = (2, 4)
+            >>> csr_tensor = CSRTensor(indptr, indices, values, shape)
+            >>> print(csr_tensor.to_dense())
+            [[1. 0. 0. 0.]
+             [0. 2. 0. 0.]]
         """
         return tensor_operator_registry.get("csr_to_dense")(self)
 
@@ -883,6 +1105,17 @@ class CSRTensor(CSRTensor_):
 
         Supported Platforms:
             ``Ascend`` ``GPU`` ``CPU``
+
+        Examples:
+            >>> import mindspore as ms
+            >>> from mindspore import Tensor, CSRTensor
+            >>> indptr = Tensor([0, 1, 2], dtype=ms.int32)
+            >>> indices = Tensor([0, 1], dtype=ms.int32)
+            >>> values = Tensor([-1, -2], dtype=ms.float32)
+            >>> shape = (2, 4)
+            >>> csr_tensor = CSRTensor(indptr, indices, values, shape)
+            >>> print(csr_tensor.abs().values)
+            [1. 2.]
         """
         data = self.values.abs()
         return CSRTensor(self.indptr, self.indices, data, self.shape)

mindspore/common/symbol.py

@@ -0,0 +1,122 @@
+# Copyright 2024 Huawei Technologies Co., Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ============================================================================
+"""Symbol implementation."""
+
+__all__ = ['Symbol']
+
+
+class Symbol:
+    r"""
+    Symbol is a data structure to indicate the symbolic info of shape.
+
+    For dynamic shape networks, compared with only setting the unknown dimensions ( ``None`` ) in `Tensor` , providing
+    more symbolic shape info can help the framework better optimize the computation graph, to improve the performce of
+    network execution.
+
+    Args:
+        max (int): The maximum length of this dimension, which is valid when it's greater than `min`. Default: ``0`` .
+        min (int): The minimum length of this dimension. Default: ``1`` .
+        divisor (int): The divisor( :math:`d` ). When `remainder` is 0, it means this dimension can be divided by
+            :math:`d` . Default: ``1`` .
+        remainder (int): The remainder( :math:`r` ) when symbol is represented by :math:`d * N + r, N \ge 1` .
+            Default: ``0`` .
+        unique (bool): When the symbol object is used multiple times, if `unique` is ``True`` , the shape items of this
+            symbol are considered to be same length, otherwise only symbol info is shared by multiple dimensions.
+            Default: ``False`` .
+
+    Outputs:
+        Symbol.
+
+    Raises:
+        TypeError: If `max`, `min`, `divisor`, `remainder` is not an int.
+        TypeError: If `unique` is not a bool.
+        ValueError: If `min` is not positive value.
+        ValueError: If `divisor` is not positive value.
+        ValueError: If `remainder` is not in the range :math:`[0, d)` .
+
+    Examples:
+        >>> import numpy as np
+        >>> import mindspore as ms
+        >>> from mindspore import nn, Tensor, Symbol
+        >>>
+        >>> class Net(nn.Cell):
+        ...     def __init__(self):
+        ...         super(Net, self).__init__()
+        ...         self.abs = ms.ops.Abs()
+        ...     def construct(self, x):
+        ...         return self.abs(x)
+        ...
+        >>> net = Net()
+        >>> s1 = Symbol(divisor=8, remainder=1)
+        >>> s2 = Symbol(max=32, unique=True)
+        >>> dyn_t = Tensor(shape=(None, s1, s1, s2, s2), dtype=ms.float32)
+        >>> net.set_inputs(dyn_t)
+        >>> # the shape values of last two dimensions must be equal, because "s2" is set to "unique"
+        >>> net(Tensor(np.random.randn(1, 9, 17, 32, 32), dtype=ms.float32)).shape
+        (1, 9, 17, 32, 32)
+        >>> net(Tensor(np.random.randn(8, 25, 9, 30, 30), dtype=ms.float32)).shape
+        (8, 25, 9, 30, 30)
+    """
+
+    def __init__(self, max=0, min=1, divisor=1, remainder=0, unique=False, **kawgs):
+        Symbol._check_args_type(max, min, divisor, remainder, unique)
+        if min <= 0:
+            raise ValueError("For 'Symbol', the 'min' value should be positive, but got {}".format(min))
+        if divisor <= 0:
+            raise ValueError("For 'Symbol', the 'divisor' value should be positive, but got {}".format(divisor))
+        if remainder < 0 or remainder >= divisor:
+            raise ValueError(
+                "For 'Symbol', the 'remainder' value should be in the range '[0, {})', but got {}".format(
+                    divisor, remainder))
+        self.max = max
+        self.min = min
+        self.divisor = divisor
+        self.remainder = remainder
+        self.unique = unique
+        self.id = id(self)
+
+    def __str__(self):
+        return str(self.to_dict())
+
+    @staticmethod
+    def _check_args_type(maxv, minv, divisor, remainder, unique):
+        """Check the type of arguments."""
+        if not isinstance(maxv, int):
+            raise TypeError(f"For 'Symbol', the argument 'max' must be int, but got {type(maxv)}")
+        if not isinstance(minv, int):
+            raise TypeError(f"For 'Symbol', the argument 'min' must be int, but got {type(minv)}")
+        if not isinstance(divisor, int):
+            raise TypeError(f"For 'Symbol', the argument 'divisor' must be int, but got {type(divisor)}")
+        if not isinstance(remainder, int):
+            raise TypeError(f"For 'Symbol', the argument 'remainder' must be int, but got {type(remainder)}")
+        if not isinstance(unique, bool):
+            raise TypeError(f"For 'Symbol', the argument 'unique' must be bool, but got {type(unique)}")
+
+    # pylint: disable=missing-docstring
+    def to_dict(self):
+        # Convert the symbolic info to dictionary.
+        # This method is not necessary to show in public api document, use comment instead of docstring.
+        res = {}
+        if self.max > self.min:
+            res["max"] = self.max
+        if self.min > self.divisor + self.remainder:  # the symbol is "d * N + r" and N >= 1
+            res["min"] = self.min
+        if self.divisor != 1:
+            res["divisor"] = self.divisor
+        if self.remainder != 0:
+            res["remainder"] = self.remainder
+        if self.unique:
+            res["id"] = self.id
+        return res