From a8de0a73e2db376a3d6349ec3cd6b71f0e925f4a Mon Sep 17 00:00:00 2001 From: maning202007 Date: Fri, 25 Mar 2022 16:08:59 +0800 Subject: [PATCH] Fix format in dump API Add note for summary to put code into the main entry change for api_python SummaryRecord --- .../mindspore/mindspore.set_dump.rst | 10 +++---- ...dspore.train.callback.SummaryCollector.rst | 1 + ...dspore.train.callback.SummaryLandscape.rst | 1 + .../mindspore.train.summary.SummaryRecord.rst | 3 +- mindspore/python/mindspore/common/dump.py | 28 ++++++++----------- .../mindspore/train/callback/_landscape.py | 3 +- .../train/callback/_summary_collector.py | 11 ++++---- .../mindspore/train/summary/summary_record.py | 11 ++++---- 8 files changed, 35 insertions(+), 33 deletions(-) diff --git a/docs/api/api_python/mindspore/mindspore.set_dump.rst b/docs/api/api_python/mindspore/mindspore.set_dump.rst index b81c7ff0dce..eb303d0d1d2 100644 --- a/docs/api/api_python/mindspore/mindspore.set_dump.rst +++ b/docs/api/api_python/mindspore/mindspore.set_dump.rst @@ -3,9 +3,9 @@ mindspore.set_dump .. py:class:: mindspore.set_dump(target, enabled=True) - 启用或者禁用target及其子节点的Dump数据功能。 + 启用或者禁用 `target` 及其子节点的Dump数据功能。 - target为 `Cell `_ 或 `Primitive `_ 的实例。请注意，此API仅在开启异步Dump功能且Dump配置文件中的 `dump_mode` 字段为"2"时生效。有关详细信息，请参阅 `Dump功能文档 `_ 。默认状态下，Cell和Primitive实例不使能Dump数据功能。 + `target` 为 :class:`mindspore.nn.Cell` 或 :class:`mindspore.ops.Primitive` 的实例。请注意，此API仅在开启异步Dump功能且Dump配置文件中的 `dump_mode` 字段为"2"时生效。有关详细信息，请参阅 `Dump功能文档 `_ 。默认状态下， :class:`mindspore.nn.Cell` 和 :class:`mindspore.ops.Primitive` 实例不使能Dump数据功能。 .. Warning:: 此类中的所有API均为实验版本，将来可能更改或者删除。 @@ -13,10 +13,10 @@ mindspore.set_dump .. Note:: - 此API只在Ascend后端的图模式有效。 - 此API只支持训练开始前调用。如果在训练过程中调用这个API，可能不会有效果。 - - 使用set_dump(Cell, True)后，Cell正向计算和反向计算（梯度运算产生的计算）中的算子会被Dump。 - - 对于 `nn.SoftMaxCrossEntropyWithLogits 层 `_ ，正向计算和反向计算使用同一组算子。因此，只能看到反向计算中的Dump数据。请注意，当使用sparse=True和reduce=“mean”初始化时，nn.SoftmaxCrossEntropyWithLogits层也将在内部使用这些算子。 + - 使用 `set_dump(Cell, True)` 后，Cell正向计算和反向计算（梯度运算产生的计算）中的算子会被Dump。 + - 对于 :class:`mindspore.nn.SoftMaxCrossEntropyWithLogits` 层，正向计算和反向计算使用同一组算子。因此，只能看到反向计算中的Dump数据。请注意，当使用 `sparse=True` 和 `reduce=“mean”` 初始化时， :class:`mindspore.nn.SoftmaxCrossEntropyWithLogits` 层也将在内部使用这些算子。 **参数：** - **target** (Union[Cell, Primitive]) - 要设置Dump标志的Cell或Primitive的实例。 - - **enabled** (bool) - True表示启用Dump，False表示禁用Dump，默认值: True。 \ No newline at end of file + - **enabled** (bool，可选) - True表示启用Dump，False表示禁用Dump，默认值：True。 \ No newline at end of file diff --git a/docs/api/api_python/train/mindspore.train.callback.SummaryCollector.rst b/docs/api/api_python/train/mindspore.train.callback.SummaryCollector.rst index 8342058e4cd..3261aa9fb1c 100644 --- a/docs/api/api_python/train/mindspore.train.callback.SummaryCollector.rst +++ b/docs/api/api_python/train/mindspore.train.callback.SummaryCollector.rst @@ -6,6 +6,7 @@ SummaryCollector还可以允许通过 `summary算子 `_ 将数据收集到summary文件中。 .. note:: + - 使用SummaryCollector时，需要将代码放置到 `if __name__ == "__main__"` 中运行。 - 不允许在回调列表中存在多个SummaryCollector实例。 - 并非所有信息都可以在训练阶段或评估阶段收集。 - SummaryCollector始终记录summary算子收集的数据。 diff --git a/docs/api/api_python/train/mindspore.train.callback.SummaryLandscape.rst b/docs/api/api_python/train/mindspore.train.callback.SummaryLandscape.rst index f857044458b..86303718679 100644 --- a/docs/api/api_python/train/mindspore.train.callback.SummaryLandscape.rst +++ b/docs/api/api_python/train/mindspore.train.callback.SummaryLandscape.rst @@ -3,6 +3,7 @@ SummaryLandscape可以帮助您收集loss地形图的信息。通过计算loss，可以在PCA（Principal Component Analysis）方向或者随机方向创建地形图。 .. note:: + - 使用SummaryLandscape时，需要将代码放置到 `if __name__ == "__main__"` 中运行。 - SummaryLandscape仅支持Linux系统。 **参数：** diff --git a/docs/api/api_python/train/mindspore.train.summary.SummaryRecord.rst b/docs/api/api_python/train/mindspore.train.summary.SummaryRecord.rst index e6d71b5f0ac..95922157ad4 100644 --- a/docs/api/api_python/train/mindspore.train.summary.SummaryRecord.rst +++ b/docs/api/api_python/train/mindspore.train.summary.SummaryRecord.rst @@ -7,6 +7,7 @@ 它通过执行 `record` 方法将数据写入文件。除了通过 `summary算子 `_ 记录网络的数据外，SummaryRecord还支持通过 `自定义回调函数和自定义训练循环 `_ 记录数据。 .. note:: + - 使用SummaryRecord时，需要将代码放置到 `if __name__ == "__main__"` 中运行。 - 确保在最后关闭SummaryRecord，否则进程不会退出。请参阅下面的示例部分，了解如何用两种方式正确关闭SummaryRecord。 - 每次训练只允许创建一个SummaryRecord实例，否则会导致数据写入异常。 - SummaryRecord仅支持Linux系统。 @@ -93,7 +94,7 @@ - **step** (int) - 表示当前的step。 - **train_network** (Cell) - 表示用于保存计算图的训练网络。默认值：None，表示当原始网络的图为None时，不保存计算图。 - - **plugin_filter** (Callable[[str], bool]) - 过滤器函数，用于过滤需要写入的标签项。默认值：None。 + - **plugin_filter** (Callable[[str], bool], 可选) - 过滤器函数，用于过滤需要写入的标签项。默认值：None。 **返回：** diff --git a/mindspore/python/mindspore/common/dump.py b/mindspore/python/mindspore/common/dump.py index f80878fc127..f4c374ab21d 100644 --- a/mindspore/python/mindspore/common/dump.py +++ b/mindspore/python/mindspore/common/dump.py @@ -21,14 +21,13 @@ from mindspore._c_expression import security def set_dump(target, enabled=True): """ - Enable or disable dump for the target and its contents. + Enable or disable dump for the `target` and its contents. - Target should be an instance of `Cell `_ or `Primitive `_ . Please note that this API takes - effect only when Asynchronous Dump is enabled and the dump_mode field in dump config file is 2. See the - `dump document `_ - for details. The default enabled status for a cell or primitive is False. + `target` should be an instance of :class:`mindspore.nn.Cell` or :class:`mindspore.ops.Primitive` . + Please note that this API takes effect only when Asynchronous Dump is enabled and the `dump_mode` + field in dump config file is "2". See the `dump document `_ for details. + The default enabled status for a :class:`mindspore.nn.Cell` or :class:`mindspore.ops.Primitive` is False. .. warning:: This is an experimental prototype that is subject to change or deletion. @@ -37,23 +36,20 @@ def set_dump(target, enabled=True): 1. This API is only effective for GRAPH_MODE with Ascend backend. 2. This API only supports being called before training starts. If you call this API during training, it may not be effective. - 3. After using set_dump(cell, True), operators in forward and backward + 3. After using `set_dump(Cell, True)` , operators in forward and backward computation (computation generated by the grad operations) of the cell will be dumped. - 4. For `nn.SparseSoftmaxCrossEntropyWithLogits - `_ layer, the forward + 4. For :class:`mindspore.nn.SoftmaxCrossEntropyWithLogits` layer, the forward computation and backward computation use the same set of operators. So you can only see dump data from backward computation. - Please note that nn.SoftmaxCrossEntropyWithLogits layer will also use - the above operators internally when initialized with sparse=True and - reduction="mean". + Please note that :class:`mindspore.nn.SoftmaxCrossEntropyWithLogits` layer will also use + the above operators internally when initialized with `sparse=True` and + `reduction="mean"` . Args: target (Union[Cell, Primitive]): The Cell instance or Primitive instance to which the dump flag is set. - enabled (bool): True means enable dump, False means disable dump. + enabled (bool, optional): True means enable dump, False means disable dump. Default: True. Supported Platforms: diff --git a/mindspore/python/mindspore/train/callback/_landscape.py b/mindspore/python/mindspore/train/callback/_landscape.py index 0fa7164bfab..937645ea533 100644 --- a/mindspore/python/mindspore/train/callback/_landscape.py +++ b/mindspore/python/mindspore/train/callback/_landscape.py @@ -169,7 +169,8 @@ class SummaryLandscape: It can create landscape in PCA direction or random direction by calculating loss. Note: - 1. SummaryLandscape only supports Linux systems. + 1. When using SummaryLandscape, you need to run the code in `if __name__ == "__main__"` . + 2. SummaryLandscape only supports Linux systems. Args: summary_dir (str): The path of summary is used to save the model weight, diff --git a/mindspore/python/mindspore/train/callback/_summary_collector.py b/mindspore/python/mindspore/train/callback/_summary_collector.py index 2957d2f6b11..07fa46998d0 100644 --- a/mindspore/python/mindspore/train/callback/_summary_collector.py +++ b/mindspore/python/mindspore/train/callback/_summary_collector.py @@ -75,11 +75,12 @@ class SummaryCollector(Callback): SummaryCollector also enables the summary operator to collect data to summary files. Note: - 1. Multiple SummaryCollector instances in callback list are not allowed. - 2. Not all information is collected at the training phase or at the eval phase. - 3. SummaryCollector always record the data collected by the summary operator. - 4. SummaryCollector only supports Linux systems. - 5. The Summary is not supported when compile source with `-s on` option. + 1. When using SummaryCollector, you need to run the code in `if __name__ == "__main__"` . + 2. Multiple SummaryCollector instances in callback list are not allowed. + 3. Not all information is collected at the training phase or at the eval phase. + 4. SummaryCollector always record the data collected by the summary operator. + 5. SummaryCollector only supports Linux systems. + 6. The Summary is not supported when compile source with `-s on` option. Args: summary_dir (str): The collected data will be persisted to this directory. diff --git a/mindspore/python/mindspore/train/summary/summary_record.py b/mindspore/python/mindspore/train/summary/summary_record.py index 71b39d48d1d..25b690189a4 100644 --- a/mindspore/python/mindspore/train/summary/summary_record.py +++ b/mindspore/python/mindspore/train/summary/summary_record.py @@ -101,11 +101,12 @@ class SummaryRecord: can be added by calling add_value. Note: - 1. Make sure to close the SummaryRecord at the end, otherwise the process will not exit. + 1. When using SummaryRecord, you need to run the code in `if __name__ == "__main__"` . + 2. Make sure to close the SummaryRecord at the end, otherwise the process will not exit. Please see the Example section below to learn how to close properly in two ways. - 2. Only one SummaryRecord instance is allowed at a time, otherwise it will cause data writing problems. - 3. SummaryRecord only supports Linux systems. - 4. The Summary is not supported when compile source with `-s on` option. + 3. Only one SummaryRecord instance is allowed at a time, otherwise it will cause data writing problems. + 4. SummaryRecord only supports Linux systems. + 5. The Summary is not supported when compile source with `-s on` option. Args: log_dir (str): The log_dir is a directory location to save the summary. @@ -334,7 +335,7 @@ class SummaryRecord: step (int): Represents training step number. train_network (Cell): The spare network for saving graph. Default: None, it means just do not save the graph summary when the original network graph is None. - plugin_filter (Optional[Callable[[str], bool]]): The filter function, \ + plugin_filter (Callable[[str], bool], optional): The filter function, \ which is used to filter out which plugin should be written. Default: None. Returns: