mindspore 1.10.0__cp37-none-any.whl → 2.0.0rc1__cp37-none-any.whl

mindspore/ops/operations/debug_ops.py

@@ -1,4 +1,4 @@
-# Copyright 2020-2021 Huawei Technologies Co., Ltd
+# Copyright 2020-2023 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.
@@ -13,30 +13,29 @@
 # limitations under the License.
 # ============================================================================
 """debug_ops"""
-from __future__ import absolute_import
 from types import FunctionType, MethodType
 
-from mindspore import context
 from mindspore import log as logger
 from mindspore._c_expression import security
 from mindspore._c_expression import Tensor as Tensor_
-from mindspore._checkparam import Validator as validator
-from mindspore._checkparam import Rel
+from mindspore import _checkparam as validator
 from mindspore.common import dtype as mstype
 from mindspore.common.parameter import Parameter
+from mindspore.common.tensor import Tensor
 from mindspore.ops.primitive import prim_attr_register, Primitive, PrimitiveWithInfer
 
 
-def _check_mode(class_name):
-    """Check for PyNative mode."""
-    mode = context.get_context('mode')
-    if mode == context.PYNATIVE_MODE:
-        raise RuntimeError(f"For '{class_name}', the operator does not support PyNative mode.")
+SUMMARY_TENSOR_CACHE = []
+
+
+def _cache_summary_data(op_name, define_name, tensor):
+    """Cache summary tensor data."""
+    global SUMMARY_TENSOR_CACHE
+    SUMMARY_TENSOR_CACHE.append([op_name, define_name, tensor])
 
 
 def _check_summary_param(name, value, class_name):
     """Checks the name and value is valid for summary."""
-    _check_mode(class_name)
     n_type = name['dtype']
     n_value = name['value']
     validator.check_value_type('name', n_type, [type(mstype.string)], class_name)
@@ -56,22 +55,28 @@ SUMMARY_RETURN_VALUE = {'dtype': mstype.int32, 'shape': [1], 'value': None}
 
 class ScalarSummary(Primitive):
     """
-    Outputs a scalar to a protocol buffer through a scalar summary operator.
+    This operator will put a scalar to a summary file with protocol buffer format. It must be used with SummaryRecord
+    or SummaryCollector, which specify the directory of the summary file. The summary file can
+    be loaded and shown by MindInsight, see `MindInsight documents <https://www.mindspore.cn/
+    mindinsight/docs/en/r2.0/index.html>`_ for details.
 
     Inputs:
         - **name** (str) - The name of the input variable, it must not be an empty string.
-        - **value** (Tensor) - The value of scalar, and the shape of value must be [] or [1].
+        - **value** (Tensor) - The value of scalar, and the dim of `value` must be 0 or 1.
 
     Raises:
         TypeError: If `name` is not a str.
         TypeError: If `value` is not a Tensor.
+        ValueError: If dim of `value` is greater than 1.
 
     Supported Platforms:
         ``Ascend`` ``GPU`` ``CPU``
 
     Examples:
+        >>> import mindspore
         >>> import mindspore.nn as nn
         >>> import mindspore.ops as ops
+        >>> from mindspore import Tensor, set_context
         >>>
         >>>
         >>> class SummaryDemo(nn.Cell):
@@ -85,7 +90,10 @@ class ScalarSummary(Primitive):
         ...         self.summary(name, x)
         ...         x = self.add(x, y)
         ...         return x
-        ...
+        >>> set_context(mode=mindspore.GRAPH_MODE)
+        >>> summary = SummaryDemo()(Tensor(3), Tensor(4))
+        >>> print(summary)
+        7
     """
 
     @prim_attr_register
@@ -98,12 +106,15 @@ class ScalarSummary(Primitive):
         self.add_prim_attr("side_effect_io", True)
 
     def __call__(self, *args):
-        raise RuntimeError(f"PyNative not support Operator '{self.__class__.__name__}'")
+        _cache_summary_data(self.name, args[0], args[1])
 
 
 class ImageSummary(PrimitiveWithInfer):
     """
-    Outputs the image tensor to protocol buffer through image summary operator.
+    This operator will put an image tensor to a summary file with protocol buffer format. It must be used with
+    SummaryRecord or SummaryCollector, which specify the directory of the summary file. The summary file can
+    be loaded and shown by MindInsight, see `MindInsight documents <https://www.mindspore.cn/
+    mindinsight/docs/en/r2.0/index.html>`_ for details.
 
     Inputs:
         - **name** (str) - The name of the input variable, it must not be an empty string.
@@ -129,8 +140,8 @@ class ImageSummary(PrimitiveWithInfer):
         ...
         ...     def construct(self, x):
         ...         name = "image"
-        ...         out = self.summary(name, x)
-        ...         return out
+        ...         self.summary(name, x)
+        ...         return x
         ...
     """
 
@@ -156,12 +167,15 @@ class ImageSummary(PrimitiveWithInfer):
         return SUMMARY_RETURN_VALUE
 
     def __call__(self, *args):
-        raise RuntimeError(f"PyNative not support Operator '{self.__class__.__name__}'")
+        _cache_summary_data(self.name, args[0], args[1])
 
 
 class TensorSummary(Primitive):
     """
-    Outputs a tensor to a protocol buffer through a tensor summary operator.
+    This operator will put a tensor to a summary file with protocol buffer format. It must be used with SummaryRecord
+    or SummaryCollector, which specify the directory of the summary file. The summary file can
+    be loaded and shown by MindInsight, see `MindInsight documents <https://www.mindspore.cn/
+    mindinsight/docs/en/r2.0/index.html>`_ for details.
 
     Inputs:
         - **name** (str) - The name of the input variable.
@@ -170,13 +184,16 @@ class TensorSummary(Primitive):
     Raises:
         TypeError: If `name` is not a str.
         TypeError: If `value` is not a Tensor.
+        ValueError: If rank of `value` is 0.
 
     Supported Platforms:
         ``Ascend`` ``GPU`` ``CPU``
 
     Examples:
+        >>> import mindspore
         >>> import mindspore.nn as nn
         >>> import mindspore.ops as ops
+        >>> from mindspore import Tensor, set_context
         >>>
         >>>
         >>> class SummaryDemo(nn.Cell):
@@ -190,7 +207,10 @@ class TensorSummary(Primitive):
         ...         name = "x"
         ...         self.summary(name, x)
         ...         return x
-        ...
+        >>> set_context(mode=mindspore.GRAPH_MODE)
+        >>> summary = SummaryDemo()(Tensor([[1]]), Tensor([[2]]))
+        >>> print(summary)
+        [[3]]
     """
 
     @prim_attr_register
@@ -203,12 +223,15 @@ class TensorSummary(Primitive):
         self.add_prim_attr("side_effect_io", True)
 
     def __call__(self, *args):
-        raise RuntimeError(f"PyNative not support Operator '{self.__class__.__name__}'")
+        _cache_summary_data(self.name, args[0], args[1])
 
 
 class HistogramSummary(PrimitiveWithInfer):
     """
-    Outputs the tensor to protocol buffer through histogram summary operator.
+    This operator will calculate the histogram of a tensor and put it to a summary file with protocol buffer format.
+    It must be used with SummaryRecord or SummaryCollector, which specify the directory of the summary file.
+    The summary file can be loaded and shown by MindInsight, see `MindInsight documents <https://www.mindspore.cn/
+    mindinsight/docs/en/r2.0/index.html>`_ for details.
 
     Inputs:
         - **name** (str) - The name of the input variable.
@@ -222,8 +245,10 @@ class HistogramSummary(PrimitiveWithInfer):
         ``Ascend`` ``GPU`` ``CPU``
 
     Examples:
+        >>> import mindspore
         >>> import mindspore.nn as nn
         >>> import mindspore.ops as ops
+        >>> from mindspore import Tensor, set_context
         >>>
         >>>
         >>> class SummaryDemo(nn.Cell):
@@ -237,7 +262,10 @@ class HistogramSummary(PrimitiveWithInfer):
         ...         name = "x"
         ...         self.summary(name, x)
         ...         return x
-        ...
+        >>> set_context(mode=mindspore.GRAPH_MODE)
+        >>> summary = SummaryDemo()(Tensor([1, 2]), Tensor([3, 4]))
+        >>> print(summary)
+        [4 6]
     """
 
     @prim_attr_register
@@ -261,7 +289,7 @@ class HistogramSummary(PrimitiveWithInfer):
         return SUMMARY_RETURN_VALUE
 
     def __call__(self, *args):
-        raise RuntimeError(f"PyNative not support Operator '{self.__class__.__name__}'")
+        _cache_summary_data(self.name, args[0], args[1])
 
 
 class InsertGradientOf(PrimitiveWithInfer):
@@ -285,7 +313,7 @@ class InsertGradientOf(PrimitiveWithInfer):
 
     Examples:
         >>> import numpy as np
-        >>> from mindspore import Tensor, ops, ms_function
+        >>> from mindspore import Tensor, ops, jit
         >>> a = Tensor(np.array([1.0]).astype(np.float32))
         >>> b = Tensor(np.array([0.2]).astype(np.float32))
         >>> def clip_gradient(dx):
@@ -307,7 +335,7 @@ class InsertGradientOf(PrimitiveWithInfer):
         ...         c = x * y
         ...         return c
         ...
-        ...     @ms_function
+        ...     @jit
         ...     def f(x, y):
         ...         return clip_test(x, y)
         ...
@@ -350,11 +378,11 @@ class HookBackward(PrimitiveWithInfer):
 
     Args:
         hook_fn (Function): Python function. hook function.
-        cell_id (str): Used to identify whether the function registered by the hook is actually registered on
+        cell_id (str, optional): Used to identify whether the function registered by the hook is actually registered on
                        the specified cell object. For example, 'nn.Conv2d' is a cell object.
-                       The default value of cell_id is empty string(""), in this case, the system will automatically
-                       register a value of cell_id.
-                       The value of cell_id currently does not support custom values.
+                       The default value of `cell_id` is empty string(""), in this case, the system will automatically
+                       register a value of `cell_id`.
+                       The value of `cell_id` currently does not support custom values.
 
     Inputs:
         - **input** (Tensor) - The variable to hook.
@@ -424,9 +452,9 @@ class HookBackward(PrimitiveWithInfer):
 
 class Print(Primitive):
     """
-    Outputs the inputs to stdout.
+    Print the inputs to stdout.
 
-    Refer to :func:`mindspore.ops.print` for more detail.
+    Refer to :func:`mindspore.ops.print_` for more detail.
 
     Supported Platforms:
         ``Ascend`` ``GPU`` ``CPU``
@@ -447,11 +475,11 @@ class Print(Primitive):
         >>> result = net(x, y)
         Print Tensor x and Tensor y:
         Tensor(shape=[2, 1], dtype=Int32, value=
-        [[1]
+        [[1],
          [1]])
         Tensor(shape=[2, 2], dtype=Int32, value=
-        [[1 1]
-         [1 1]])
+        [[1, 1],
+         [1, 1]])
     """
 
     @prim_attr_register
@@ -466,7 +494,7 @@ class Print(Primitive):
         for arg in args:
             if isinstance(arg, Parameter):
                 print(Tensor_.__repr__(arg))
-            elif isinstance(arg, Tensor_):
+            elif isinstance(arg, (Tensor, Tensor_)):
                 print(arg.__repr__())
             else:
                 print(arg)
@@ -474,33 +502,43 @@ class Print(Primitive):
 
 class Assert(PrimitiveWithInfer):
     """
-    Asserts that the given condition is True.
-    If input condition evaluates to false, print the list of tensor in data.
+    Asserts whether the given condition is True.
+    If input condition is identified to be false, print a list of the tensor in data.
 
     Args:
-        summarize (int): Print this many entries of each tensor.
+        summarize (int, optional): The number of entries to be printed in each tensor while the given condition is
+            identified to be False. Default: 3.
 
     Inputs:
-        - **condition** [Union[Tensor[bool], bool]] - The condition to evaluate.
-        - **input_data** (Union(tuple[Tensor], list[Tensor])) - The tensors to print out when condition is false.
+        - **condition** (Union[Tensor[bool], bool]) - The condition to be identified.
+        - **input_data** (Union[tuple[Tensor], list[Tensor]]) - The tensors to be printed out when the condition
+          is false.
 
     Raises:
         TypeError: If `summarize` is not an int.
         TypeError: If `condition` is neither a Tensor nor a bool.
         TypeError: If `input_data` is neither a tuple nor a list.
 
+    Supported Platforms:
+        ``GPU`` ``CPU``
+
     Examples:
-        >>> class AssertDemo(nn.Cell):
-        ...     def __init__(self):
-        ...         super(AssertDemo, self).__init__()
-        ...         self.assert1 = ops.Assert(summarize=10)
-        ...         self.add = ops.Add()
-        ...
-        ...     def construct(self, x, y):
-        ...         data = self.add(x, y)
-        ...         self.assert1(True, [data])
-        ...         return data
-        ...
+        >>> a = Tensor(np.array([-1, 0, 1, 2, 3]).astype(np.int32))
+        >>> b = Tensor(np.array([1, 2, 3, 4, 5]).astype(np.float32))
+        >>> assert1 = ops.Assert(3)
+        >>> assert1(False, [a, b])
+        For 'Assert' condition is false.
+        input data: [-1 0 1]
+        input data: [1 2 3]
+        Traceback (most recent call last):
+          File "<stdin>", line 1, in <module>
+          File "mindspore/ops/primitive.py", line 294, in __call__
+            return _run_op(self, self.name, args)
+          File "mindspore/common/api.py", line 99, in wrapper
+            results = fn(*arg, **kwargs)
+          File "mindspore/ops/primitive.py", line 743, in _run_op
+            output = real_run_op(obj, op_name, args)
+        RuntimeError: assert failed
     """
 
     @prim_attr_register
@@ -514,7 +552,7 @@ class Assert(PrimitiveWithInfer):
 
     def infer_shape(self, condition, inputs):
         condition_len = len(condition)
-        validator.check_int(condition_len, 1, Rel.LE, "condition's rank", self.name)
+        validator.check_int(condition_len, 1, validator.LE, "condition's rank", self.name)
         if condition_len == 1:
             validator.check_equal_int(condition[0], 1, "condition[0]", self.name)
         return [1]