!662 Add some notices for using same name to record data by summary operator

Merge pull request !662 from ougongchang/fix_same_tag

tutorials/source_en/advanced_use/dashboard.md

@@ -34,11 +34,11 @@ Figure 1 shows a change process of loss values during the neural network trainin
 
 Buttons from left to right in the upper right corner of the figure are used to display the chart in full screen, switch the Y-axis scale, enable or disable the rectangle selection, roll back the chart step by step, and restore the chart.
 
-- Full-screen Display: Display the scalar curve in full screen. Click the button again to restore it.
-- Switch Y-axis Scale: Perform logarithmic conversion on the Y-axis coordinate.
-- Enable/Disable Rectangle Selection: Draw a rectangle to select and zoom in a part of the chart. You can perform rectangle selection again on the zoomed-in chart.
+- Full-screen display: Display the scalar curve in full screen. Click the button again to restore it.
+- Switch Y-axis scale: Perform logarithmic conversion on the Y-axis coordinate.
+- Enable/Disable rectangle selection: Draw a rectangle to select and zoom in a part of the chart. You can perform rectangle selection again on the zoomed-in chart.
 - Step-by-step Rollback: Cancel operations step by step after continuously drawing rectangles to select and zooming in the same area.
-- Restore Chart: Restore a chart to the original state.
+- Restore chart: Restore a chart to the original state.
 
 There can set the threshold value to highlight the value or delete the threshold value in the lower right corner of the figure. As shown in the figure, the threshold set is less than 0.3, highlighted in red shows what is below the threshold, and it is intuitive to see the expected data value or some unusual value.
 
@@ -48,10 +48,10 @@ Figure 2: Scalar visualization function area
 
 Figure 2 shows the scalar visualization function area, which allows you to view scalar information by selecting different tags, different dimensions of the horizontal axis, and smoothness.
 
-- Tag: Select the required tags to view the corresponding scalar information.
-- Horizontal Axis: Select any of Step, Relative Time, and Absolute Time as the horizontal axis of the scalar curve.
-- Smoothness: Adjust the smoothness to smooth the scalar curve.
-- Scalar Synthesis: Synthesize two scalar curves and display them in a chart to facilitate comparison between the two curves or view the synthesized chart.
+- Tag selection: Select the required tags to view the corresponding scalar information.
+- Horizontal axis: Select any of Step, Relative Time, and Absolute Time as the horizontal axis of the scalar curve.
+- Smoothness: adjust the smoothness to smooth the scalar curve.
+- Scalar synthesis: Synthesize two scalar curves and display them in a chart to facilitate comparison between the two curves or view the synthesized chart.
 
 ![scalar_compound.png](./images/scalar_compound.png)
 
@@ -112,8 +112,8 @@ Figure 8: Dataset graph function area
 Figure 8 shows the dataset graph function area which includes the following content:
 
 - Legend: Display the meaning of each icon in the data lineage graph.
-- Data Processing Pipeline: Display the data processing pipeline used for training. Select a single node in the graph to view details.
-- Node Information: Display basic information about the selected node, including names and parameters of the data processing and augmentation operators.
+- Data processing pipeline: Display the data processing pipeline used for training. Select a single node in the graph to view details.
+- Node information: Display basic information about the selected node, including names and parameters of the data processing and augmentation operators.
 
 ## Image Visualization
 
@@ -132,8 +132,8 @@ Figure 10: Image visualization function area
 Figure 10 shows the function area of image visualization. You can view image information by selecting different tags, brightness, and contrast.
 
 - Tag: Select the required tags to view the corresponding image information.
-- Brightness Adjustment: Adjust the brightness of all displayed images.
-- Contrast Adjustment: Adjust the contrast of all displayed images.
+- Brightness adjustment: Adjust the brightness of all displayed images.
+- Contrast adjustment: Adjust the contrast of all displayed images.
 
 ## Tensor Visualization
 

tutorials/source_en/advanced_use/summary_record.md

@@ -122,7 +122,15 @@ model.eval(ds_eval, callbacks=[summary_collector])
 
 ### Method two: Custom collection of network data with summary operators and SummaryCollector
 
-In addition to providing the `SummaryCollector` that automatically collects some summary data, MindSpore provides summary operators that enable custom collection other data on the network, such as the input of each convolutional layer, or the loss value in the loss function, etc. The recording method is shown in the following steps.
+In addition to providing the `SummaryCollector` that automatically collects some summary data, MindSpore provides summary operators that enable custom collection other data on the network, such as the input of each convolutional layer, or the loss value in the loss function, etc. 
+
+Summary operators currently supported:
+- [ScalarSummary](https://www.mindspore.cn/api/en/master/api/python/mindspore/mindspore.ops.operations.html?highlight=scalarsummary#mindspore.ops.operations.ScalarSummary): Record a scalar data.
+- [TensorSummary](https://www.mindspore.cn/api/en/master/api/python/mindspore/mindspore.ops.operations.html?highlight=tensorsummary#mindspore.ops.operations.TensorSummary): Record a tensor data.
+- [ImageSummary](https://www.mindspore.cn/api/en/master/api/python/mindspore/mindspore.ops.operations.html?highlight=imagesummary#mindspore.ops.operations.ImageSummary): Record a image data.
+- [HistogramSummary](https://www.mindspore.cn/api/en/master/api/python/mindspore/mindspore.ops.operations.html?highlight=histogramsummar#mindspore.ops.operations.HistogramSummary): Convert tensor data into histogram data records.
+
+The recording method is shown in the following steps.
 
 Step 1: Call the summary operator in the `construct` function of the derived class that inherits `nn.Cell` to collect image or scalar data.
 
@@ -151,7 +159,7 @@ class CrossEntropyLoss(nn.Cell):
         self.off_value = Tensor(0.0, mstype.float32)
 
         # Init ScalarSummary
-        self.sm_scalar = P.ScalarSummary()
+        self.scalar_summary = P.ScalarSummary()
 
     def construct(self, logits, label):
         label = self.one_hot(label, F.shape(logits)[1], self.on_value, self.off_value)
@@ -159,7 +167,7 @@ class CrossEntropyLoss(nn.Cell):
         loss = self.mean(loss, (-1,))
 
         # Record loss
-        self.sm_scalar("loss", loss)
+        self.scalar_summary("loss", loss)
         return loss
 
 
@@ -168,14 +176,14 @@ class MyOptimizer(Optimizer):
     def __init__(self, learning_rate, params, ......):
         ......
         # Initialize ScalarSummary
-        self.sm_scalar = P.ScalarSummary()
+        self.scalar_summary = P.ScalarSummary()
         self.histogram_summary = P.HistogramSummary()
         self.weight_names = [param.name for param in self.parameters]
 
     def construct(self, grads):
         ......
         # Record learning rate here
-        self.sm_scalar("learning_rate", learning_rate)
+        self.scalar_summary("learning_rate", learning_rate)
 
         # Record weight
         self.histogram_summary(self.weight_names[0], self.paramters[0])
@@ -192,19 +200,22 @@ class Net(nn.Cell):
         ......
 
         # Init ImageSummary
-        self.sm_image = P.ImageSummary()
+        self.image_summary = P.ImageSummary()
         # Init TensorSummary
-        self.sm_tensor = P.TensorSummary()
+        self.tensor_summary = P.TensorSummary()
 
     def construct(self, data):
         # Record image by Summary operator
-        self.sm_image("image", data)
+        self.image_summary("image", data)
         # Record tensor by Summary operator
-        self.sm_tensor("tensor", data)
+        self.tensor_summary("tensor", data)
         ......
         return out
 ```
 
+> In the same Summary operator, the name given to the data must not be repeated, otherwise the data collection and presentation will have unexpected behavior.
+> For example, if two `ScalarSummary` operators are used to collect scalar data, two scalars cannot be given the same name.
+
 Step 2: In the training script, instantiate the `SummaryCollector` and apply it to `model.train`.
 
 The sample code is as follows:

tutorials/source_zh_cn/advanced_use/dashboard.md

@@ -49,7 +49,7 @@
 
 图2展示的标量可视化的功能区，提供了根据选择不同标签，水平轴的不同维度和平滑度来查看标量信息的功能。
 
-- 标签：提供了对所有标签进行多项选择的功能，用户可以通过勾选所需的标签，查看对应的标量信息。
+- 标签选择：提供了对所有标签进行多项选择的功能，用户可以通过勾选所需的标签，查看对应的标量信息。
 - 水平轴：可以选择“步骤”、“相对时间”、“绝对时间”中的任意一项，来作为标量曲线的水平轴。
 - 平滑度：可以通过调整平滑度，对标量曲线进行平滑处理。
 - 标量合成：可以选中两条标量曲线进行合成并展示在一个图中，以方便对两条曲线进行对比或者查看合成后的图。

tutorials/source_zh_cn/advanced_use/summary_record.md

@@ -124,7 +124,15 @@ model.eval(ds_eval, callbacks=[summary_collector])
 
 ### 方式二：结合Summary算子和SummaryCollector，自定义收集网络中的数据
 
-MindSpore除了提供 `SummaryCollector` 能够自动收集一些常见数据，还提供了Summary算子，支持在网络中自定义收集其他的数据，比如每一个卷积层的输入，或在损失函数中的损失值等。记录方式如下面的步骤所示。
+MindSpore除了提供 `SummaryCollector` 能够自动收集一些常见数据，还提供了Summary算子，支持在网络中自定义收集其他的数据，比如每一个卷积层的输入，或在损失函数中的损失值等。
+
+当前支持的Summary算子:
+- [ScalarSummary](https://www.mindspore.cn/api/zh-CN/master/api/python/mindspore/mindspore.ops.operations.html?highlight=scalarsummary#mindspore.ops.operations.ScalarSummary): 记录标量数据
+- [TensorSummary](https://www.mindspore.cn/api/zh-CN/master/api/python/mindspore/mindspore.ops.operations.html?highlight=tensorsummary#mindspore.ops.operations.TensorSummary): 记录张量数据
+- [ImageSummary](https://www.mindspore.cn/api/zh-CN/master/api/python/mindspore/mindspore.ops.operations.html?highlight=imagesummary#mindspore.ops.operations.ImageSummary): 记录图片数据
+- [HistogramSummary](https://www.mindspore.cn/api/zh-CN/master/api/python/mindspore/mindspore.ops.operations.html?highlight=histogramsummar#mindspore.ops.operations.HistogramSummary): 将张量数据转为直方图数据记录
+
+记录方式如下面的步骤所示。
 
 步骤一：在继承 `nn.Cell` 的衍生类的 `construct` 函数中调用Summary算子来采集图像或标量数据或者其他数据。
 
@@ -153,7 +161,7 @@ class CrossEntropyLoss(nn.Cell):
         self.off_value = Tensor(0.0, mstype.float32)
 
         # Init ScalarSummary
-        self.sm_scalar = P.ScalarSummary()
+        self.scalar_summary = P.ScalarSummary()
 
     def construct(self, logits, label):
         label = self.one_hot(label, F.shape(logits)[1], self.on_value, self.off_value)
@@ -161,7 +169,7 @@ class CrossEntropyLoss(nn.Cell):
         loss = self.mean(loss, (-1,))
 
         # Record loss
-        self.sm_scalar("loss", loss)
+        self.scalar_summary("loss", loss)
         return loss
 
 
@@ -170,14 +178,14 @@ class MyOptimizer(Optimizer):
     def __init__(self, learning_rate, params, ......):
         ......
         # Initialize ScalarSummary
-        self.sm_scalar = P.ScalarSummary()
+        self.scalar_summary = P.ScalarSummary()
         self.histogram_summary = P.HistogramSummary()
         self.weight_names = [param.name for param in self.parameters]
 
     def construct(self, grads):
         ......
         # Record learning rate here
-        self.sm_scalar("learning_rate", learning_rate)
+        self.scalar_summary("learning_rate", learning_rate)
 
         # Record weight
         self.histogram_summary(self.weight_names[0], self.paramters[0])
@@ -193,20 +201,23 @@ class Net(nn.Cell):
         ......
 
         # Init ImageSummary
-        self.sm_image = P.ImageSummary()
+        self.image_summary = P.ImageSummary()
         # Init TensorSummary
-        self.sm_tensor = P.TensorSummary()
+        self.tensor_summary = P.TensorSummary()
 
     def construct(self, data):
         # Record image by Summary operator
-        self.sm_image("image", data)
+        self.image_summary("image", data)
         # Record tensor by Summary operator
-        self.sm_tensor("tensor", data)
+        self.tensor_summary("tensor", data)
         ......
         return out
 
 ```
 
+> 同一种Summary算子中，给数据设置的名字不能重复，否则数据收集和展示都会出现非预期行为。
+> 比如使用两个 `ScalarSummary` 算子收集标量数据，给两个标量设置的名字不能是相同的。
+
 步骤二：在训练脚本中，实例化 `SummaryCollector`，并将其应用到 `model.train`。
 
 样例代码如下：
@@ -324,7 +335,7 @@ mindinsight stop
 
 ## 注意事项
 
-1. 为了控制列出summary列表的用时，MindInsight最多支持发现999个summary列表条目。
+1. 为了控制列出summary文件目录的用时，MindInsight最多支持发现999个summary文件目录。
 
 2. 不能同时使用多个 `SummaryRecord` 实例 （`SummaryCollector` 中使用了 `SummaryRecord`）。