Sync readme from docs changes.

mindinsight/mindconverter/README.md

@@ -8,14 +8,14 @@
     - [Overview](#overview)
     - [Installation](#installation)
     - [Usage](#usage)
-        - [PyTorch Model Scripts Migration](#PyTorch-model-scripts-migration)
-        - [TensorFlow Model Scripts Migration](#TensorFlow-model-scripts-migration)
+        - [PyTorch Model Scripts Migration](#pytorch-model-scripts-migration)
+        - [TensorFlow Model Scripts Migration](#tensorflow-model-scripts-migration)
     - [Scenario](#scenario)
     - [Example](#example)
         - [AST-Based Conversion](#ast-based-conversion)
         - [Graph-Based Conversion](#graph-based-conversion)
-            - [PyTorch Model Scripts Conversion](#PyTorch-Model-Scripts-Conversion)
-            - [TensorFlow Model Scripts Conversion](#TensorFlow-Model-Scripts-Conversion)
+            - [PyTorch Model Scripts Conversion](#pytorch-model-scripts-conversion)
+            - [TensorFlow Model Scripts Conversion](#tensorflow-model-scripts-conversion)
     - [Caution](#caution)
     - [Unsupported situation of AST mode](#unsupported-situation-of-ast-mode)
         - [Situation1](#situation1)
@@ -25,13 +25,11 @@
 
 ## Overview
 
-MindConverter is a migration tool to transform the model scripts from PyTorch or TensorFlow to Mindspore. Users can migrate their PyTorch or TensorFlow models to Mindspore rapidly with minor changes according to the conversion report.
-
+MindConverter is a migration tool to transform the model scripts from PyTorch or TensorFlow to MindSpore. Users can migrate their PyTorch or TensorFlow models to MindSpore rapidly with minor changes according to the conversion report.
 
 ## Installation
 
-Mindconverter is a submodule in MindInsight. Please follow the [Guide](https://www.mindspore.cn/install/en) here to install MindInsight.
-
+MindConverter is a submodule in MindInsight. Please follow the [Guide](https://www.mindspore.cn/install/en) here to install MindInsight.
 
 ## Usage
 
@@ -46,7 +44,7 @@ usage: mindconverter [-h] [--version] [--in_file IN_FILE]
 
 optional arguments:
   -h, --help            show this help message and exit
-  --version             show program's version number and exit
+  --version             show program version number and exit
   --in_file IN_FILE     Specify path for script file to use AST schema to do
                         script conversation.
   --model_file MODEL_FILE
@@ -55,14 +53,14 @@ optional arguments:
                         `--in_file` and `--model_file` are both provided, use
                         AST schema as default.
   --shape SHAPE         Optional, expected input tensor shape of
-                        `--model_file`. It's required when use graph based
+                        `--model_file`. It is required when use graph based
                         schema. Usage: --shape 1,3,244,244
-  --input_node INPUT_NODE
-                        Optional, input node(s) name of `--model_file`. It's
+  --input_nodes INPUT_NODE
+                        Optional, input node(s) name of `--model_file`. It is
                         required when use Tensorflow model. Usage:
                         --input_node input_1:0,input_2:0
-  --output_node OUTPUT_NODE
-                        Optional, output node(s) name of `--model_file`. It's
+  --output_nodes OUTPUT_NODE
+                        Optional, output node(s) name of `--model_file`. It is
                         required when use Tensorflow model. Usage:
                         --output_node output_1:0,output_2:0
   --output OUTPUT       Optional, specify path for converted script file
@@ -82,12 +80,13 @@ optional arguments:
 
 **MindConverter provides two modes for PyTorch：**
 
-1. **Abstract Syntax Tree (AST) based conversion**：Use the argument `--in_file` will enable the AST mode.
-2. **Computational Graph based conversion**：Use `--model_file` and `--shape` arguments will enable the Graph mode.
+1. **Abstract Syntax Tree (AST) based conversion**: Use the argument `--in_file` will enable the AST mode.
+2. **Computational Graph based conversion**: Use `--model_file` and `--shape` arguments will enable the Graph mode.
+
 
 > The AST mode will be enabled, if both `--in_file` and `--model_file` are specified.
 
-For the Graph mode, `--shape` is mandatory. 
+For the Graph mode, `--shape` is mandatory.
 
 For the AST mode, `--shape` is ignored.
 
@@ -95,8 +94,7 @@ For the AST mode, `--shape` is ignored.
 
 Please note that your original PyTorch project is included in the module search path (PYTHONPATH). Use the python interpreter and test your module can be successfully loaded by `import` command. Use `--project_path` instead if your project is not in the PYTHONPATH to ensure MindConverter can load it.
 
-> Assume the project is located at `/home/user/project/model_training`, users can use this command to add the project to `PYTHONPATH` : `export PYTHONPATH=/home/user/project/model_training:$PYTHONPATH`
-
+> Assume the project is located at `/home/user/project/model_training`, users can use this command to add the project to `PYTHONPATH` : `export PYTHONPATH=/home/user/project/model_training:$PYTHONPATH`  
 > MindConverter needs the original PyTorch scripts because of the reverse serialization.
 
 ### TensorFlow Model Scripts Migration
@@ -105,6 +103,7 @@ Please note that your original PyTorch project is included in the module search
 
 > AST mode is not supported for TensorFlow, only computational graph based mode is available.
 
+
 ## Scenario
 
 MindConverter provides two modes for different migration demands.
@@ -116,13 +115,13 @@ The AST mode is recommended for the first demand (AST mode is only supported for
 
 For the second demand, the Graph mode is recommended. As the computational graph is a standard descriptive language, it is not affected by user's coding style. This mode may have more operators converted as long as these operators are supported by MindConverter.
 
-Some typical image classification networks such as ResNet and VGG have been tested for the Graph mode. Note that: 
+Some typical image classification networks such as ResNet and VGG have been tested for the Graph mode. Note that:
 
 > 1. Currently, the Graph mode does not support models with multiple inputs. Only models with a single input and single output are supported.
 > 2. The Dropout operator will be lost after conversion because the inference mode is used to load the PyTorch or TensorFlow model. Manually re-implement is necessary.
 > 3. The Graph-based mode will be continuously developed and optimized with further updates.
 
- Supported models list:
+Supported models list:
 
 |  Supported Model | PyTorch Script | TensorFlow Script |
 | :----: | :----: | :----: |
@@ -138,6 +137,7 @@ Some typical image classification networks such as ResNet and VGG have been test
 | AlexNet | [link](https://github.com/pytorch/vision/blob/v0.5.0/torchvision/models/alexnet.py) | / |
 | GoogLeNet | [link](https://github.com/pytorch/vision/blob/v0.5.0/torchvision/models/googlenet.py) | / |
 | MobileNetV2 | [link](https://github.com/pytorch/vision/blob/v0.5.0/torchvision/models/mobilenet.py) | [link](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/python/keras/applications/mobilenet_v2.py) |
+| InceptionV3 | / | [link](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/python/keras/applications/inception_v3.py) |
 
 ## Example
 
@@ -159,8 +159,8 @@ line <row>:<col> [UnConvert] 'operator' didn't convert. ...
 
 For non-transformed operators, the original code keeps. Please manually migrate them. [Click here](https://www.mindspore.cn/doc/note/en/master/index.html#operator_api) for more information about operator mapping.
 
-
 Here is an example of the conversion report:
+
 ```text
  [Start Convert]
  [Insert] 'import mindspore.ops.operations as P' is inserted to the converted file.
@@ -173,7 +173,6 @@ Here is an example of the conversion report:
 
 For non-transformed operators, suggestions are provided in the report. For instance, MindConverter suggests that replace `torch.nn.AdaptiveAvgPool2d` with `mindspore.ops.operations.ReduceMean`.
 
-
 ### Graph-Based Conversion
 
 #### PyTorch Model Scripts Conversion
@@ -232,8 +231,7 @@ class Classifier(nn.Cell):
 
 ```
 
-> Note: `--output` and `--report` are optional. MindConverter creates an `output` folder under the current working directory, and outputs generated scripts and conversion reports to it.   
-
+> `--output` and `--report` are optional. MindConverter creates an `output` folder under the current working directory, and outputs generated scripts and conversion reports to it.
 
 #### TensorFlow Model Scripts Conversion
 
@@ -265,7 +263,7 @@ print(f"Input node name: {INPUT_NODE}, output node name: {OUTPUT_NODE}")
 
 ```
 
-After the above code is executed, the model will be saved to `/home/user/xxx/frozen_model.pb`. `INPUT_NODE` is input node name, and `OUTPUT_NODE` is output node's.
+After the above code is executed, the model will be saved to `/home/user/xxx/frozen_model.pb`. `INPUT_NODE` can be passed into `--input_nodes`, and `OUTPUT_NODE` is the corresponding `--output_nodes`.
 
 Suppose the input node name is `input_1:0`, output node name is `predictions/Softmax:0`, the input shape of model is `1,224,224,3`, the following command can be used to generate the script:
 ```shell script
@@ -276,7 +274,7 @@ mindconverter --model_file /home/user/xxx/frozen_model.pb --shape 1,224,224,3 \
               --report /home/user/output/report
 ```
 
-After executed，MindSpore script, and report file can be found in corresponding directory.
+After executed MindSpore script, and report file can be found in corresponding directory.
 
 
 The format of conversion report generated by script generation scheme based on graph structure is the same as that of AST scheme. However, since the graph based scheme is a generative method, the original pytorch script is not referenced in the conversion process. Therefore, the code line and column numbers involved in the generated conversion report refer to the generated script.
@@ -287,9 +285,9 @@ In addition, for operators that are not converted successfully, the input and ou
 
 ## Caution
 
-1. PyTorch, TensorFlow, TF2ONNX is not an explicitly stated dependency library in MindInsight. The Graph conversion requires the consistent PyTorch or TensorFlow version as the model is trained. (MindConverter recommends PyTorch 1.4.0 or 1.6.0)
-2. This script conversion tool relies on operators which supported by MindConverter and MindSpore. Unsupported operators may not successfully mapped to MindSpore operators. You can manually edit, or implement the mapping based on MindConverter, and contribute to our MindInsight repository. We appreciate your support for the MindSpore community. 
-
+1. PyTorch, TensorFlow, TF2ONNX(1.7.1) are not an explicitly stated dependency libraries in MindInsight. The Graph conversion requires the consistent PyTorch or TensorFlow version as the model is trained. (MindConverter recommends PyTorch 1.4.0 or 1.6.0)
+2. This script conversion tool relies on operators which supported by MindConverter and MindSpore. Unsupported operators may not be successfully mapped to MindSpore operators. You can manually edit, or implement the mapping based on MindConverter, and contribute to our MindInsight repository. We appreciate your support for the MindSpore community.
+3. MindConverter can only guarantee that the converted model scripts require a minor revision or no revision when the inputs' shape fed to the generated model script are equal to the value of `--shape` (The batch size dimension is not limited).
 
 ## Unsupported situation of AST mode
 

mindinsight/mindconverter/README_CN.md

@@ -7,15 +7,15 @@
 - [MindConverter教程](#mindconverter教程)
     - [概述](#概述)
     - [安装](#安装)
-    - [命令行用法](#命令行用法)
-        - [PyTorch模型脚本迁移](#PyTorch模型脚本迁移)
-        - [TensorFlow模型脚本迁移](#TensorFlow模型脚本迁移)
+    - [用法](#用法)
+        - [PyTorch模型脚本迁移](#pytorch模型脚本迁移)
+        - [TensorFlow模型脚本迁移](#tensorflow模型脚本迁移)
     - [使用场景](#使用场景)
     - [使用示例](#使用示例)
         - [基于AST的脚本转换示例](#基于ast的脚本转换示例)
         - [基于图结构的脚本生成示例](#基于图结构的脚本生成示例)
-            - [PyTorch模型脚本生成示例](#PyTorch模型脚本生成示例)
-            - [TensorFlow模型脚本生成示例](#TensorFlow模型脚本生成示例)
+            - [PyTorch模型脚本生成示例](#pytorch模型脚本生成示例)
+            - [TensorFlow模型脚本生成示例](#tensorflow模型脚本生成示例)
     - [注意事项](#注意事项)
     - [AST方案不支持场景](#ast方案不支持场景)
         - [场景1](#场景1)
@@ -25,15 +25,17 @@
 
 ## 概述
 
-MindConverter是一款用于将PyTorch，TensorFlow脚本转换到MindSpore脚本的工具。结合转换报告的信息，用户只需对转换后的脚本进行微小的改动，即可快速将PyTorch，TensorFlow框架的模型脚本迁移到MindSpore。
+MindConverter是一款用于将PyTorch、TensorFlow脚本转换到MindSpore脚本的工具。结合转换报告的信息，用户只需对转换后的脚本进行微小的改动，即可快速将PyTorch、TensorFlow框架的模型脚本迁移到MindSpore。
 
 ## 安装
 
 此工具为MindInsight的子模块，安装MindInsight后，即可使用MindConverter，MindInsight安装请参考该[安装文档](https://www.mindspore.cn/install/)。
 
-## 命令行用法
+## 用法
 
-```buildoutcfg
+MindConverter提供命令行（Command-line interface, CLI）的使用方式，命令如下。
+
+```bash
 usage: mindconverter [-h] [--version] [--in_file IN_FILE]
                      [--model_file MODEL_FILE] [--shape SHAPE]
                      [--input_node INPUT_NODE] [--output_node OUTPUT_NODE]
@@ -42,23 +44,23 @@ usage: mindconverter [-h] [--version] [--in_file IN_FILE]
 
 optional arguments:
   -h, --help            show this help message and exit
-  --version             show program's version number and exit
+  --version             show program version number and exit
   --in_file IN_FILE     Specify path for script file to use AST schema to do
                         script conversation.
   --model_file MODEL_FILE
-                        PyTorch .pth or Tensorflow .pb model file path to use
+                        PyTorch .pth or TensorFlow .pb model file path to use
                         graph based schema to do script generation. When
                         `--in_file` and `--model_file` are both provided, use
                         AST schema as default.
   --shape SHAPE         Optional, expected input tensor shape of
-                        `--model_file`. It's required when use graph based
+                        `--model_file`. It is required when use graph based
                         schema. Usage: --shape 1,3,244,244
-  --input_node INPUT_NODE
-                        Optional, input node(s) name of `--model_file`. It's
+  --input_nodes INPUT_NODE
+                        Optional, input node(s) name of `--model_file`. It is
                         required when use Tensorflow model. Usage:
                         --input_node input_1:0,input_2:0
-  --output_node OUTPUT_NODE
-                        Optional, output node(s) name of `--model_file`. It's
+  --output_nodes OUTPUT_NODE
+                        Optional, output node(s) name of `--model_file`. It is
                         required when use Tensorflow model. Usage:
                         --output_node output_1:0,output_2:0
   --output OUTPUT       Optional, specify path for converted script file
@@ -74,7 +76,6 @@ optional arguments:
 
 ```
 
-
 ### PyTorch模型脚本迁移
 
 **MindConverter提供两种PyTorch模型脚本迁移方案：**
@@ -96,13 +97,15 @@ optional arguments:
 
 ### TensorFlow模型脚本迁移
 
-**MindConverter提供基于图结构的脚本生成方案**：指定`--model_file`, `--shape`, `--input_node`, `--output_node`进行脚本迁移。
+**MindConverter提供基于图结构的脚本生成方案**：指定`--model_file`、`--shape`、`--input_node`、`--output_node`进行脚本迁移。
 
 > AST方案不支持TensorFlow模型脚本迁移，TensorFlow脚本迁移仅支持基于图结构的方案。
 
+
 ## 使用场景
 
 MindConverter提供两种技术方案，以应对不同脚本迁移场景：
+
 1. 用户希望迁移后脚本保持原脚本结构（包括变量、函数、类命名等与原脚本保持一致）；
 2. 用户希望迁移后脚本保持较高的转换率，尽量少的修改、甚至不需要修改，即可实现迁移后模型脚本的执行。
 
@@ -113,7 +116,7 @@ MindConverter提供两种技术方案，以应对不同脚本迁移场景：
 目前已基于典型图像分类网络(Resnet, VGG)对图结构的脚本转换方案进行测试。
 
 > 1. 基于图结构的脚本生成方案，目前仅支持单输入、单输出模型，对于多输入模型暂不支持；
-> 2. 基于图结构的脚本生成方案，由于要加载PyTorch, TensorFlow模型，会导致转换后网络中Dropout算子丢失，需要用户手动补齐；
+> 2. 基于图结构的脚本生成方案，由于要加载PyTorch、TensorFlow模型，会导致转换后网络中Dropout算子丢失，需要用户手动补齐；
 > 3. 基于图结构的脚本生成方案持续优化中。
 
 支持网络列表:   
@@ -132,8 +135,10 @@ MindConverter提供两种技术方案，以应对不同脚本迁移场景：
 | AlexNet | [脚本链接](https://github.com/pytorch/vision/blob/v0.5.0/torchvision/models/alexnet.py) | 暂未测试 |
 | GoogLeNet | [脚本链接](https://github.com/pytorch/vision/blob/v0.5.0/torchvision/models/googlenet.py) | 暂未测试 |
 | MobileNetV2 | [脚本链接](https://github.com/pytorch/vision/blob/v0.5.0/torchvision/models/mobilenet.py) | [脚本链接](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/python/keras/applications/mobilenet_v2.py) |
+| InceptionV3 | 暂未测试 | [脚本链接](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/python/keras/applications/inception_v3.py) |
 
 ## 使用示例
+
 ### 基于AST的脚本转换示例
 
 若用户希望使用基于AST的方案进行脚本迁移，假设原PyTorch脚本路径为`/home/user/model.py`，希望将脚本输出至`/home/user/output`，转换报告输出至`/home/user/output/report`，则脚本转换命令为：
@@ -151,6 +156,7 @@ line x:y: [UnConvert] 'operator' didn't convert. ...
 ```
 
 转换报告示例如下所示：
+
 ```text
  [Start Convert]
  [Insert] 'import mindspore.ops.operations as P' is inserted to the converted file.
@@ -163,10 +169,10 @@ line x:y: [UnConvert] 'operator' didn't convert. ...
 
 对于部分未成功转换的算子，报告中会提供修改建议，如`line 157:23`，MindConverter建议将`torch.nn.AdaptiveAvgPool2d`替换为`mindspore.ops.operations.ReduceMean`。
 
-
 ### 基于图结构的脚本生成示例
 
 #### PyTorch模型脚本生成示例
+
 若用户已将PyTorch模型保存为.pth格式，假设模型绝对路径为`/home/user/model.pth`，该模型期望的输入shape为(1, 3, 224, 224)，原PyTorch脚本位于`/home/user/project/model_training`，希望将脚本输出至`/home/user/output`，转换报告输出至`/home/user/output/report`，则脚本生成命令为：
 
 ```bash
@@ -178,10 +184,8 @@ mindconverter --model_file /home/user/model.pth --shape 1,3,224,224 \
 
 执行该命令，MindSpore代码文件、转换报告生成至相应目录。
 
-
 基于图结构的脚本生成方案产生的转换报告格式与AST方案相同。然而，由于基于图结构方案属于生成式方法，转换过程中未参考原PyTorch脚本，因此生成的转换报告中涉及的代码行、列号均指生成后脚本。
 
-
 另外对于未成功转换的算子，在代码中会相应的标识该节点输入、输出Tensor的shape（以`input_shape`, `output_shape`标识），便于用户手动修改。以Reshape算子为例（暂不支持Reshape），<a name="manual_modify">将生成如下代码</a>：
 
 ```python
@@ -225,9 +229,7 @@ class Classifier(nn.Cell):
 
 ```
 
-
-> 注意：其中`--output`与`--report`参数可省略，若省略，该命令将在当前工作目录（Working directory）下自动创建`output`目录，将生成的脚本、转换报告输出至该目录。
-
+> 其中`--output`与`--report`参数可省略，若省略，该命令将在当前工作目录（Working directory）下自动创建`output`目录，将生成的脚本、转换报告输出至该目录。
 
 #### TensorFlow模型脚本生成示例
 
@@ -245,7 +247,7 @@ def freeze_graph(graph, session, output):
         graphdef_frozen = tf.graph_util.convert_variables_to_constants(session, graphdef_inf, output)
         graph_io.write_graph(graphdef_frozen, saved_path, "frozen_model.pb", as_text=False)
 
-tf.keras.backend.set_learning_phase(0) # this line most important
+tf.keras.backend.set_learning_phase(0)
 
 base_model = InceptionV3()
 session = tf.keras.backend.get_session()
@@ -259,7 +261,7 @@ print(f"Input node name: {INPUT_NODE}, output node name: {OUTPUT_NODE}")
 
 上述代码执行完毕，模型将会保存至`/home/user/xxx/frozen_model.pb`。其中，`INPUT_NODE`为输入节点名称，`OUTPUT_NODE`为输出节点名称。
 
-假设输入节点名称为`input_1:0`, 输出节点名称为`predictions/Softmax:0`，模型输入样本尺寸为`1,224,224,3`，则可使用如下命令进行脚本生成：
+假设输入节点名称为`input_1:0`、输出节点名称为`predictions/Softmax:0`，模型输入样本尺寸为`1,224,224,3`，则可使用如下命令进行脚本生成：
 ```shell script
 mindconverter --model_file /home/user/xxx/frozen_model.pb --shape 1,224,224,3 \
               --input_node input_1:0 \
@@ -271,17 +273,17 @@ mindconverter --model_file /home/user/xxx/frozen_model.pb --shape 1,224,224,3 \
 执行该命令，MindSpore代码文件、转换报告生成至相应目录。
 
 
-基于图结构的脚本生成方案产生的转换报告格式与AST方案相同。然而，由于基于图结构方案属于生成式方法，转换过程中未参考原PyTorch脚本，因此生成的转换报告中涉及的代码行、列号均指生成后脚本。
+基于图结构的脚本生成方案产生的转换报告格式与AST方案相同。然而，由于基于图结构方案属于生成式方法，转换过程中未参考原TensorFlow脚本，因此生成的转换报告中涉及的代码行、列号均指生成后脚本。
 
 
-另外对于未成功转换的算子，在代码中会相应的标识该节点输入、输出Tensor的shape（以`input_shape`, `output_shape`标识），便于用户手动修改，示例请见[PyTorch模型脚本生成示例](#manual_modify)。
+另外，对于未成功转换的算子，在代码中会相应的标识该节点输入、输出Tensor的shape（以`input_shape`、`output_shape`标识），便于用户手动修改，示例见[PyTorch模型脚本生成示例](#manual_modify)。
 
 
 ## 注意事项
 
-1. PyTorch, TensorFlow, TF2ONNX不作为MindInsight明确声明的依赖库。若想使用基于图结构的脚本生成工具，需要用户手动安装与生成PyTorch模型版本一致的PyTorch库（MindConverter推荐使用PyTorch 1.4.0或PyTorch 1.6.0进行脚本生成），或TensorFlow；
+1. PyTorch、TensorFlow、TF2ONNX(1.7.1)不作为MindInsight明确声明的依赖库。若想使用基于图结构的脚本生成工具，需要用户手动安装与生成PyTorch模型版本一致的PyTorch库（MindConverter推荐使用PyTorch 1.4.0或PyTorch 1.6.0进行脚本生成），或TensorFlow；
 2. 脚本转换工具本质上为算子驱动，对于MindConverter未维护的PyTorch或ONNX算子与MindSpore算子映射，将会出现相应的算子无法转换的问题，对于该类算子，用户可手动修改，或基于MindConverter实现映射关系，向MindInsight仓库贡献。
-
+3. MindConverter仅保证转换后模型脚本在输入数据尺寸与`--shape`一致的情况下，可达到无需人工修改或少量修改（`--shape`中batch size维度不受限）。
 
 ## AST方案不支持场景