Chinese translation

README_zh_CN.md

@@ -19,7 +19,7 @@ NNI 管理自动机器学习 (AutoML) 的 Experiment，**调度运行**由调优
 * 想要更容易**实现或试验新的自动机器学习算法**的研究员或数据科学家，包括：超参调优算法，神经网络搜索算法以及模型压缩算法。
 * 在机器学习平台中**支持自动机器学习**。
 
-### **[NNI v1.5 已发布！](https://github.com/microsoft/nni/releases) &nbsp;[<img width="48" src="docs/img/release_icon.png" />](#nni-released-reminder)**
+### **[NNI v1.6 已发布！](https://github.com/microsoft/nni/releases) &nbsp;[<img width="48" src="docs/img/release_icon.png" />](#nni-released-reminder)**
 
 ## **NNI 功能一览**
 
@@ -186,6 +186,7 @@ NNI 提供命令行工具以及友好的 WebUI 来管理训练的 Experiment。
       <ul>
         <li><a href="docs/zh_CN/Tuner/CustomizeTuner.md">自定义 Tuner</a></li>
         <li><a href="docs/zh_CN/Assessor/CustomizeAssessor.md">自定义 Assessor</a></li>
+        <li><a href="docs/zh_CN/Tutorial/InstallCustomizedAlgos.md">安装自定义的 Tuner，Assessor，Advisor</a></li>
       </ul>
       </td>
         <td style="border-top:#FF0000 solid 0px;">
@@ -223,7 +224,7 @@ Linux 和 macOS 下 NNI 系统需求[参考这里](https://nni.readthedocs.io/zh
 注意：
 
 * 如果遇到任何权限问题，可添加 `--user` 在用户目录中安装 NNI。
-* 目前，Windows 上的 NNI 支持本机，远程和 OpenPAI 模式。 强烈推荐使用 Anaconda 或 Miniconda 在 Windows 上安装 NNI。
+* 目前，Windows 上的 NNI 支持本机，远程和 OpenPAI 模式。 强烈推荐使用 Anaconda 或 Miniconda [在 Windows 上安装 NNI](docs/zh_CN/Tutorial/InstallationWin.md)。
 * 如果遇到如 `Segmentation fault` 等错误参考[常见问题](docs/zh_CN/Tutorial/FAQ.md)。 Windows 上的 FAQ 参考[在 Windows 上使用 NNI](docs/zh_CN/Tutorial/InstallationWin.md#faq)。
 
 ### **验证安装**
@@ -233,7 +234,7 @@ Linux 和 macOS 下 NNI 系统需求[参考这里](https://nni.readthedocs.io/zh
 * 通过克隆源代码下载示例。
 
    ```bash
-   git clone -b v1.5 https://github.com/Microsoft/nni.git
+   git clone -b v1.6 https://github.com/Microsoft/nni.git
    ```
 
 * 运行 MNIST 示例。
@@ -316,8 +317,7 @@ You can use these commands to get more information about the experiment
 经作者许可的一些 NNI 用法示例和相关文档。
 
 * ### **外部代码库** ### 
-   * 在 NNI 中运行 [ENAS](examples/tuners/enas_nni/README_zh_CN.md)
-   * 在 NNI 中运行 [神经网络架构结构搜索](examples/trials/nas_cifar10/README_zh_CN.md)
+   * 在 NNI 中运行 [ENAS](examples/nas/enas/README_zh_CN.md)
    * [NNI 中的自动特征工程](examples/feature_engineering/auto-feature-engineering/README_zh_CN.md)
    * 使用 NNI 的 [矩阵分解超参调优](https://github.com/microsoft/recommenders/blob/master/notebooks/04_model_select_and_optimize/nni_surprise_svd.ipynb)
    * [scikit-nni](https://github.com/ksachdeva/scikit-nni) 使用 NNI 为 scikit-learn 开发的超参搜索。
@@ -339,9 +339,9 @@ You can use these commands to get more information about the experiment
 
 加入聊天组： 
 
-| Gitter                                                                                                      |   | 微信                                                                                          |
-| ----------------------------------------------------------------------------------------------------------- | - | ------------------------------------------------------------------------------------------- |
-| ![图片](https://user-images.githubusercontent.com/39592018/80665738-e0574a80-8acc-11ea-91bc-0836dc4cbf89.png) | 或 | ![图片](https://github.com/JSong-Jia/NNI-user-group/blob/master/user%20group%20code_0512.jpg) |
+| Gitter                                                                                                      |   | 微信                                                                      |
+| ----------------------------------------------------------------------------------------------------------- | - | ----------------------------------------------------------------------- |
+| ![图片](https://user-images.githubusercontent.com/39592018/80665738-e0574a80-8acc-11ea-91bc-0836dc4cbf89.png) | 或 | ![image](https://github.com/scarlett2018/nniutil/raw/master/wechat.png) |
 
 ## 相关项目
 

docs/zh_CN/Assessor/BuiltinAssessor.md

@@ -55,12 +55,13 @@ assessor:
 
 适用于各种性能曲线，可用到各种场景中来加速优化过程。 更好的地方是，它能处理并评估性能类似的曲线。 [详细说明](./CurvefittingAssessor.md)
 
+**注意**，根据原始论文，仅支持递增函数。 因此，此 Assessor 仅可用于最大化优化指标的场景。 例如，它可用于准确度，但不能用于损失值。
+
 **classArgs 要求：**
 
 * **epoch_num** (*int, **必需***) - epoch 的总数。 需要此数据来决定需要预测点的总数。
-* **optimize_mode** (*maximize 或 minimize, 可选, 默认值为 maximize*) - 如果为 'maximize', Assessor 会在结果小于期望值时**终止** Trial。 如果为 'minimize'，Assessor 会在结果大于期望值时**终止** Trial。
 * **start_step** (*int, 可选, 默认值为 6*) - 只有收到 start_step 个中间结果后，才开始判断是否一个 Trial 应该被终止。
-* **threshold** (*float, 可选, 默认值为 0.95*) - 用来确定提前终止较差结果的阈值。 例如，如果 threshold = 0.95, optimize_mode = maximize，最好的历史结果是 0.9，那么会在 Trial 的预测值低于 0.95 * 0.9 = 0.855 时停止。
+* **threshold** (*float, 可选, 默认值为 0.95*) - 用来确定提前终止较差结果的阈值。 例如，如果 threshold = 0.95，最好的历史结果是 0.9，那么会在 Trial 的预测值低于 0.95 * 0.9 = 0.855 时停止。
 * **gap** (*int, 可选, 默认值为 1*) - Assessor 两次评估之间的间隔次数。 例如：如果 gap = 2, start_step = 6，就会评估第 6, 8, 10, 12... 个中间结果。
 
 **使用示例：**
@@ -71,7 +72,6 @@ assessor:
     builtinAssessorName: Curvefitting
     classArgs:
       epoch_num: 20
-      optimize_mode: maximize
       start_step: 6
       threshold: 0.95
       gap: 1

docs/zh_CN/Assessor/CurvefittingAssessor.md

@@ -1,20 +1,20 @@
 # NNI 中的 Curve Fitting Assessor
 
-## 1. 介绍
+## 介绍
 
 Curve Fitting Assessor 是一个 LPA (learning, predicting, assessing，即学习、预测、评估) 的算法。 如果预测的 Trial X 在 step S 比性能最好的 Trial 要差，就会提前终止它。
 
 此算法中采用了 12 种曲线来拟合学习曲线。 这组参数曲线模型来自于[参考论文](http://aad.informatik.uni-freiburg.de/papers/15-IJCAI-Extrapolation_of_Learning_Curves.pdf)。 学习曲线的形状与先验知识是一致的：都是典型的递增的、饱和的函数。
 
-![](../../img/curvefitting_learning_curve.PNG)
+![learning_curve](../../img/curvefitting_learning_curve.PNG)
 
 所有学习曲线模型被合并到了单个，更强大的模型中。 合并的模型通过加权线性混合：
 
-![](../../img/curvefitting_f_comb.gif)
+![f_comb](../../img/curvefitting_f_comb.gif)
 
 合并后的新参数向量
 
-![](../../img/curvefitting_expression_xi.gif)
+![expression_xi](../../img/curvefitting_expression_xi.gif)
 
 假设增加一个高斯噪声，且噪声参数初始化为最大似然估计。
 
@@ -30,43 +30,44 @@ Curve Fitting Assessor 是一个 LPA (learning, predicting, assessing，即学
 
 下图显示了此算法在 MNIST Trial 历史数据上结果。其中绿点表示 Assessor 获得的数据，蓝点表示将来，但未知的数据，红色线条是 Curve fitting Assessor 的预测曲线。
 
-![](../../img/curvefitting_example.PNG)
+![示例](../../img/curvefitting_example.PNG)
 
-## 2. 用法
+## 用法
 
 要使用 Curve Fitting Assessor，需要在 Experiment 的 YAML 配置文件进行如下改动。
 
-    assessor:
-        builtinAssessorName: Curvefitting
-        classArgs:
-          # (必须) epoch 的总数。
-          # 需要此数据来决定需要预测的点。
-          epoch_num: 20
-          # (可选) 选项: maximize, minimize
-          *  optimize_mode 的默认值是 maximize
-          optimize_mode: maximize
-          # (可选) 为了节约计算资源，在收到了 start_step 个中间结果后，才开始预测。
-          # start_step 的默认值是 6。
-          start_step: 6
-          # (可选) 决定是否提前终止的阈值。
-          # 例如，如果 threshold = 0.95, optimize_mode = maximize，最好的历史结果是 0.9，那么会在 Trial 的预测值低于 0.95 * 0.9 = 0.855 时停止。
-          * 阈值的默认值是 0.95。
-          # 注意：如果选择了 minimize 模式，要让 threshold >= 1.0 (如 threshold=1.1)
-          threshold: 0.95
-          # (可选) gap 是两次评估之间的间隔次数。
-          # 例如：如果 gap = 2, start_step = 6，就会评估第 6, 8, 10, 12... 个中间结果。
-          * gap 的默认值是 1。
-          gap: 1
-
-
-## 3. 文件结构
+```yaml
+assessor:
+  builtinAssessorName: Curvefitting
+  classArgs:
+    # (必须) epoch 的总数。
+    # 需要此数据来决定需要预测的点。
+    epoch_num: 20
+    # (可选) 为了节约计算资源，仅在收到 start_step 个中间结果后，才开始进行预测。
+    # start_step 的默认值是 6。
+    start_step: 6
+    # (可选) 决定是否提前终止的阈值。
+    # 例如，如果 threshold = 0.95，最好的历史结果是 0.9，那么会在 Trial 的预测值低于 0.95 * 0.9 = 0.855 时停止。
+    # 阈值的默认值是 0.95。
+    threshold: 0.95
+    # (可选) gap 是两次评估之间的间隔次数。
+    # 例如：如果 gap = 2, start_step = 6，就会评估第 6, 8, 10, 12... 个中间结果。
+    # gap 的默认值是 1。
+    gap: 1
+```
+
+## 局限性
+
+根据原始论文，仅支持递增函数。 因此，此 Assessor 仅可用于最大化优化指标的场景。 例如，它可用于准确度，但不能用于损失值。
+
+## 文件结构
 
 Assessor 有大量的文件、函数和类。 在这里，会简要描述其中一部分。
 
 * `curvefunctions.py` 包含了所有函数表达式和默认参数。
 * `modelfactory.py` 包括学习和预测部分，并实现了相应的计算部分。
 * `curvefitting_assessor.py` 是接收 Trial 历史数据并评估是否需要提前终止的 Assessor。
 
-## 4. TODO
+## TODO
 
 * 进一步提高预测精度，并在更多模型上测试。

docs/zh_CN/Compressor/CompressionReference.md

@@ -0,0 +1,33 @@
+# 模型压缩 Python API 参考
+
+```eval_rst
+.. contents::
+```
+
+## 灵敏度工具
+
+```eval_rst
+..  autoclass:: nni.compression.torch.utils.sensitivity_analysis.SensitivityAnalysis
+    :members:
+
+```
+
+## 拓扑结构工具
+
+```eval_rst
+..  autoclass:: nni.compression.torch.utils.shape_dependency.ChannelDependency
+    :members:
+
+..  autoclass:: nni.compression.torch.utils.shape_dependency.GroupDependency
+    :members:
+
+..  autoclass:: nni.compression.torch.utils.mask_conflict.CatMaskPadding
+    :members:
+
+..  autoclass:: nni.compression.torch.utils.mask_conflict.GroupMaskConflict
+    :members:
+
+..  autoclass:: nni.compression.torch.utils.mask_conflict.ChannelMaskConflict
+    :members:
+
+```

docs/zh_CN/Compressor/CompressionUtils.md

@@ -0,0 +1,119 @@
+# 模型压缩分析工具
+
+```eval_rst
+.. contents::
+```
+
+NNI 提供了几种易于使用的工具，在压缩时用于分析模型。
+
+## 灵敏度分析
+首先提供的是灵敏度分析工具 (**SensitivityAnalysis**)，用于分析模型中每个卷积层的灵敏度。 具体来说，SensitiviyAnalysis 会为每层逐渐剪枝，同时测试模型的精度变化。 注意，敏感度分析一次只会对一层进行剪枝，其它层会使用它们原始的权重。 根据不同稀疏度下不同卷积层的精度，可以很容易的找出模型精度对哪些层的变化更敏感。
+
+### 用法
+
+下列代码是 SensitivityAnalysis 的基本用法。
+```python
+from nni.compression.torch.utils.sensitivity_analysis import SensitivityAnalysis
+
+def val(model):
+    model.eval()
+    total = 0
+    correct = 0
+    with torch.no_grad():
+        for batchid, (data, label) in enumerate(val_loader):
+            data, label = data.cuda(), label.cuda()
+            out = model(data)
+            _, predicted = out.max(1)
+            total += data.size(0)
+            correct += predicted.eq(label).sum().item()
+    return correct / total
+
+s_analyzer = SensitivityAnalysis(model=net, val_func=val)
+sensitivity = s_analyzer.analysis(val_args=[net])
+os.makedir(outdir)
+s_analyzer.export(os.path.join(outdir, filename))
+```
+
+SensitivityAnalysis 的两个重要参数是 `model`, 和 `val_func`。 `model` 是要分析的神经网络，`val_func` 是返回验证数据集的精度、损失或其它指标的验证函数。 根据不同的场景，可能需要不同的方法来计算损失和精度，因此用户需要定义能返回模型精度、损失的函数，并传给 SensitivityAnalysis。 上面的示例也展示了如何用 SensitivityAnalysis 将敏感度结果导出为 csv 文件。
+
+除此之外，还可以使用可选参数 `sparsities` 来为每一层设置稀疏度值。
+```python
+s_analyzer = SensitivityAnalysis(model=net, val_func=val, sparsities=[0.25, 0.5, 0.75])
+```
+SensitivityAnalysis 会为每一层逐渐剪枝 25% 50% 75% 的权重，并同时记录模型精度 (SensitivityAnalysis 一次只修建一层，其他层会使用原始权重)。 如果没有设置稀疏度，SensitivityAnalysis 会将 numpy.arange(0.1, 1.0, 0.1) 作为默认的稀疏度值。
+
+还可以通过 early_stop_mode 和 early_stop_value 选项来加快灵敏度分析。 默认情况下，SensitivityAnalysis 会为每一层测试所有的稀疏度值下的精度。 而设置了 early_stop_mode 和 early_stop_value 后，当精度或损失值到了 early_stop_value 所设置的阈值时，会停止灵敏度分析。 支持的提前终止模式包括：minimize, maximize, dropped, raised。
+
+minimize: 当 val_func 的返回值低于 `early_stop_value` 时，会停止分析。
+
+maximize: 当 val_func 的返回值大于 `early_stop_value` 时，会停止分析。
+
+dropped: 当验证指标下降 `early_stop_value` 时，会停止分析。
+
+raised: 当验证指标增加 `early_stop_value` 时，会停止分析。
+
+```python
+s_analyzer = SensitivityAnalysis(model=net, val_func=val, sparsities=[0.25, 0.5, 0.75], early_stop_mode='dropped', early_stop_value=0.1)
+```
+如果只想分析部分卷积层，可在分析函数中通过 `specified_layers` 指定。 `specified_layers` 是卷积层的 Pytorch 模块名称。 例如：
+```python
+sensitivity = s_analyzer.analysis(val_args=[net], specified_layers=['Conv1'])
+```
+在此例中，只会分析 `Conv1` 层。 另外，也可以通过并行启动多个进程，将同一个模型的不同层分给每个进程来加速。
+
+
+### 输出示例
+下面是从 SensitivityAnalysis 中导出的 csv 文件示例。 第一行由 'layername' 和稀疏度值的列表组成。 稀疏度值表示 SensitivityAnalysis 为每一层剪枝的权重比例。 每行表示某层在不同稀疏度下的模型精度。 注意，根据 early_stop 选项，某些层可能不会有所有稀疏度下的精度或损失值。比如，精度下降的值超过了定义的阈值。
+```
+layername,0.05,0.1,0.2,0.3,0.4,0.5,0.7,0.85,0.95
+features.0,0.54566,0.46308,0.06978,0.0374,0.03024,0.01512,0.00866,0.00492,0.00184
+features.3,0.54878,0.51184,0.37978,0.19814,0.07178,0.02114,0.00438,0.00442,0.00142
+features.6,0.55128,0.53566,0.4887,0.4167,0.31178,0.19152,0.08612,0.01258,0.00236
+features.8,0.55696,0.54194,0.48892,0.42986,0.33048,0.2266,0.09566,0.02348,0.0056
+features.10,0.55468,0.5394,0.49576,0.4291,0.3591,0.28138,0.14256,0.05446,0.01578
+```
+
+## 拓扑结构分析
+NNI 还提供了在模型压缩过程中，进行模型拓扑分析的工具。 这些工具可帮助用户更好的压缩模型。 压缩模型时，因为网络结构的复杂性，经常需要花时间检查压缩配置是否合理。 因此，NNI 提供了这些工具用于模型拓扑分析，来减轻用户负担。
+
+### ChannelDependency
+复杂模型中还会有残差或连接的操作。 对这些模型剪枝时，需要小心卷积层之间通道数量的依赖关系。 以 resnet18 中残差模块为例。 `layer2.0.conv2` 和 `layer2.0.downsample.0` 层输出的特征会加到一起，所以 `layer2.0.conv2` 和 `layer2.0.downsample.0` 的输出通道数量必须一样，否则会有 Tensor 形状的冲突。
+
+![](../../img/channel_dependency_example.jpg)
+
+
+如果有通道依赖的图层，被分配了不同的稀疏度 (此处仅讨论 L1FilterPruner/L2FilterPruner 的结构化剪枝)，就会造成形状冲突。 即使剪枝后的掩码模型也能正常使用，剪枝后的模型也因为模型在加和、连接这些层的输出时有冲突，不能在设备上加速。 此工具可用于查找有通道依赖的层，帮助更好的剪枝模型。
+
+#### 用法
+```python
+from nni.compression.torch.utils.shape_dependency import ChannelDependency
+data = torch.ones(1, 3, 224, 224).cuda()
+channel_depen = ChannelDependency(net, data)
+channel_depen.export('dependency.csv')
+```
+
+#### Output Example
+下列代码是 由 ChannelDependency 导出的 torchvision.models.resnet18 示例。 每行上，有相互依赖的输出通道。 例如，layer1.1.conv2, conv1 和 layer1.0.conv2 相互间有输出依赖。这表示这三个层的输出通道（过滤器）数量需要一致，否则模型会产生形状冲突。
+```
+Dependency Set,Convolutional Layers
+Set 1,layer1.1.conv2,layer1.0.conv2,conv1
+Set 2,layer1.0.conv1
+Set 3,layer1.1.conv1
+Set 4,layer2.0.conv1
+Set 5,layer2.1.conv2,layer2.0.conv2,layer2.0.downsample.0
+Set 6,layer2.1.conv1
+Set 7,layer3.0.conv1
+Set 8,layer3.0.downsample.0,layer3.1.conv2,layer3.0.conv2
+Set 9,layer3.1.conv1
+Set 10,layer4.0.conv1
+Set 11,layer4.0.downsample.0,layer4.1.conv2,layer4.0.conv2
+Set 12,layer4.1.conv1
+```
+
+### 掩码冲突
+当不同层的掩码有冲突时，（例如，为通道依赖的层设置了不同的稀疏度），可通过 MaskConflict 来修复。 即，MaskConflict 可加载由 (L1FilterPruner, 等) 导出的掩码，并检查是否有掩码冲突。如果有 MaskConflict 会将冲突的掩码设置为相同的值。
+
+```
+from nni.compression.torch.utils.mask_conflict import fix_mask_conflict
+fixed_mask = fix_mask_conflict('./resnet18_mask', net, data)
+```