Merge pull request #200 from microsoft/master

merge master

docs/zh_CN/EvolutionTuner.md → docs/zh_CN/Tuner/EvolutionTuner.md

-# Naive Evolution Tuner
+# Naïve Evolution Tuner
 
-## Naive Evolution（进化算法）
+## Naïve Evolution（进化算法）
 
 进化算法来自于 [Large-Scale Evolution of Image Classifiers](https://arxiv.org/pdf/1703.01041.pdf)。 它会基于搜索空间随机生成一个种群。 在每一代中，会选择较好的结果，并对其下一代进行一些变异（例如，改动一个超参，增加或减少一层）。 进化算法需要很多次 Trial 才能有效，但它也非常简单，也很容易扩展新功能。
\ No newline at end of file

docs/zh_CN/GridsearchTuner.md → docs/zh_CN/Tuner/GridsearchTuner.md

@@ -2,4 +2,4 @@
 
 ## Grid Search（遍历搜索）
 
-Grid Search 会穷举定义在搜索空间文件中的所有超参组合。 注意，搜索空间仅支持 `choice`, `quniform`, `qloguniform`。 `quniform` 和 `qloguniform` 中的 **数字 `q` 有不同的含义（与[搜索空间](SearchSpaceSpec.md)说明不同）。 这里的意义是在 `low` 和 `high` 之间均匀取值的数量。</p>
+Grid Search 会穷举定义在搜索空间文件中的所有超参组合。 注意，搜索空间仅支持 `choice`, `quniform`, `qloguniform`。 `quniform` 和 `qloguniform` 中的 **数字 `q` 有不同的含义（与[搜索空间](../Tutorial/SearchSpaceSpec.md)说明不同）。 这里的意义是在 `low` 和 `high` 之间均匀取值的数量。</p>
\ No newline at end of file

docs/zh_CN/HyperoptTuner.md → docs/zh_CN/Tuner/HyperoptTuner.md

@@ -4,10 +4,33 @@
 
 Tree-structured Parzen Estimator (TPE) 是一种 sequential model-based optimization（SMBO，即基于序列模型优化）的方法。 SMBO 方法根据历史指标数据来按顺序构造模型，来估算超参的性能，随后基于此模型来选择新的超参。 TPE 方法对 P(x|y) 和 P(y) 建模，其中 x 表示超参，y 表示相关的评估指标。 P(x|y) 通过变换超参的生成过程来建模，用非参数密度（non-parametric densities）代替配置的先验分布。 细节可参考 [Algorithms for Hyper-Parameter Optimization](https://papers.nips.cc/paper/4443-algorithms-for-hyper-parameter-optimization.pdf)。 ​
 
+### TPE 的并行优化
+
+为了利用多个计算节点，TPE 方法是异步运行的，这样能避免浪费时间等待 Trial 评估的完成。 此算法设计的初衷是优化序列。 当在高并发情况下使用 TPE 时，性能会非常差。 通过 Constant Liar 算法优化了这种情况。 关于优化的原理，参考[文档](../CommunitySharings/ParallelizingTpeSearch.md)。
+
+### 用法
+
+要使用 TPE，需要在 Experiment 的 YAML 配置文件进行如下改动：
+
+```yaml
+tuner:
+  builtinTunerName: TPE
+  classArgs:
+    optimize_mode: maximize
+    parallel_optimize: True
+    constant_liar_type: min
+```
+
+**参数**
+
+* **optimize_mode** (*maximize 或 minimize, 可选项, 默认值为 maximize*) - 如果为 'maximize'，表示 Tuner 的目标是将指标最大化。 如果为 'minimize'，表示 Tuner 的目标是将指标最小化。
+* **parallel_optimize** (*bool, 可选, 默认值为 False*) - 如果为 True，TPE 会使用 Constant Liar 算法来优化并行超参调优。 否则，TPE 不会区分序列或并发的情况。
+* **constant_liar_type** (*min、max 或 mean, 可选, 默认值为 min*) - 使用的 constant liar 类型，会在 X 点根据 y 的取值来确定。对应三个值：min{Y}, max{Y}, 和 mean{Y}。
+
 ## Random Search（随机搜索）
 
 [Random Search for Hyper-Parameter Optimization](http://www.jmlr.org/papers/volume13/bergstra12a/bergstra12a.pdf) 中介绍了随机搜索惊人的简单和效果。 建议当不清楚超参的先验分布时，采用随机搜索作为基准。
 
 ## Anneal（退火算法）
 
-这种简单的退火算法从先前的采样开始，会越来越靠近发现的最佳点取样。 此算法是随机搜索的简单变体，利用了响应面的平滑性。 退火率不是自适应的。
+这种简单的退火算法从先前的采样开始，会越来越靠近发现的最佳点取样。 此算法是随机搜索的简单变体，利用了反应曲面的平滑性。 退火率不是自适应的。
\ No newline at end of file

docs/zh_CN/SmacTuner.md → docs/zh_CN/Tuner/SmacTuner.md

@@ -4,4 +4,4 @@
 
 [SMAC](https://www.cs.ubc.ca/~hutter/papers/10-TR-SMAC.pdf) 基于 Sequential Model-Based Optimization (SMBO). 它利用使用过的结果好的模型（高斯随机过程模型），并将随机森林引入到 SMBO 中，来处理分类参数。 NNI 的 SMAC 通过包装 [SMAC3](https://github.com/automl/SMAC3) 来支持。
 
-NNI 中的 SMAC 只支持部分类型的[搜索空间](SearchSpaceSpec.md)，包括`choice`, `randint`, `uniform`, `loguniform`, `quniform(q=1)`。
+NNI 中的 SMAC 只支持部分类型的[搜索空间](../Tutorial/SearchSpaceSpec.md)，包括`choice`, `randint`, `uniform`, `loguniform`, `quniform(q=1)`。
\ No newline at end of file

docs/zh_CN/AnnotationSpec.md → docs/zh_CN/Tutorial/AnnotationSpec.md

@@ -36,9 +36,9 @@ NNI 支持如下 10 种类型来表示搜索空间：
 - `@nni.variable(nni.choice(option1,option2,...,optionN),name=variable)` 变量值是选项中的一种，这些变量可以是任意的表达式。
 - `@nni.variable(nni.randint(lower, upper),name=variable)` 变量值的公式为：round(uniform(low, high))。 目前，值的类型为 float。 如果要使用整数，需要显式转换。
 - `@nni.variable(nni.uniform(low, high),name=variable)` 变量值会是 low 和 high 之间均匀分布的某个值。
-- `@nni.variable(nni.quniform(low, high, q),name=variable)` 变量值会是 low 和 high 之间均匀分布的某个值，公式为：round(uniform(low, high) / q) * q
+- `@nni.variable(nni.quniform(low, high, q),name=variable)` 变量值为 clip(round(uniform(low, high) / q) * q, low, high)，clip 操作用于约束生成值的边界。
 - `@nni.variable(nni.loguniform(low, high),name=variable)` 变量值是 exp(uniform(low, high)) 的点，数值以对数均匀分布。
-- `@nni.variable(nni.qloguniform(low, high, q),name=variable)` 变量值会是 low 和 high 之间均匀分布的某个值，公式为：round(exp(uniform(low, high)) / q) * q
+- `@nni.variable(nni.qloguniform(low, high, q),name=variable)` 变量值为 clip(round(loguniform(low, high) / q) * q, low, high)，clip 操作用于约束生成值的边界。
 - `@nni.variable(nni.normal(mu, sigma),name=variable)` 变量值为正态分布的实数值，平均值为 mu，标准方差为 sigma。
 - `@nni.variable(nni.qnormal(mu, sigma, q),name=variable)` 变量值分布的公式为： round(normal(mu, sigma) / q) * q
 - `@nni.variable(nni.lognormal(mu, sigma),name=variable)` 变量值分布的公式为： exp(normal(mu, sigma))
@@ -73,10 +73,10 @@ h_pooling = max_pool(hidden_layer, pool_size)
 
 `'''@nni.report_intermediate_result(metrics)'''`
 
-`@nni.report_intermediate_result` 用来返回中间结果，这和 <Trials.md> 中的 `nni.report_intermediate_result` 用法一样。
+`@nni.report_intermediate_result` 用来返回中间结果，这和[在 NNI 上实现 Trial](../TrialExample/Trials.md) 中 `nni.report_intermediate_result` 的用法一样。
 
 ### 4. 最终结果
 
 `'''@nni.report_final_result(metrics)'''`
 
-`@nni.report_final_result` 用来返回当前 Trial 的最终结果，这和 <Trials.md> 中的 `nni.report_final_result` 用法一样。
+`@nni.report_final_result` 用来返回当前 Trial 的最终结果，这和[在 NNI 上实现 Trial](../TrialExample/Trials.md) 中的 `nni.report_final_result` 用法一样。
\ No newline at end of file

docs/zh_CN/Contributing.md → docs/zh_CN/Tutorial/Contributing.md

@@ -6,7 +6,7 @@
 
 不管怎样，如果想要更有效的贡献代码，可以阅读以下内容。 本文档包括了所有在贡献中需要注意的要点，会加快合并代码、解决问题的速度。
 
-查看[快速入门](./QuickStart.md)来初步了解。
+查看[快速入门](QuickStart.md)来初步了解。
 
 下面是一些简单的贡献指南。
 

docs/zh_CN/ExperimentConfig.md → docs/zh_CN/Tutorial/ExperimentConfig.md

@@ -22,8 +22,12 @@ maxTrialNum:
 #可选项: local, remote, pai, kubeflow
 trainingServicePlatform:
 searchSpacePath:
-#可选项: true, false
+#可选项: true, false, 默认值: false
 useAnnotation:
+#可选项: true, false, 默认值: false
+multiPhase:
+#可选项: true, false, 默认值: false
+multiThread:
 tuner:
   #可选项: TPE, Random, Anneal, Evolution
   builtinTunerName:
@@ -54,8 +58,12 @@ maxTrialNum:
 #可选项: local, remote, pai, kubeflow
 trainingServicePlatform: 
 searchSpacePath: 
-#可选项: true, false
+#可选项: true, false, 默认值: false
 useAnnotation:
+#可选项: true, false, 默认值: false
+multiPhase:
+#可选项: true, false, 默认值: false
+multiThread:
 tuner:
   #可选项: TPE, Random, Anneal, Evolution
   builtinTunerName:
@@ -92,8 +100,12 @@ maxExecDuration:
 maxTrialNum: 
 #可选项: local, remote, pai, kubeflow
 trainingServicePlatform: 
-#可选项: true, false
+#可选项: true, false, 默认值: false
 useAnnotation:
+#可选项: true, false, 默认值: false
+multiPhase:
+#可选项: true, false, 默认值: false
+multiThread:
 tuner:
   #可选项: TPE, Random, Anneal, Evolution
   builtinTunerName:
@@ -184,9 +196,9 @@ machineList:
     
     - **remote** 将任务提交到远程的 Ubuntu 上，必须用 **machineList** 来指定远程的 SSH 连接信息。
     
-    - **pai** 提交任务到微软开源的 [OpenPAI](https://github.com/Microsoft/pai) 上。 更多 OpenPAI 配置，参考 [pai 模式](./PaiMode.md)。
+    - **pai** 提交任务到微软开源的 [OpenPAI](https://github.com/Microsoft/pai) 上。 更多 OpenPAI 配置，参考 [pai 模式](../TrainingService/PaiMode.md)。
     
-    - **kubeflow** 提交任务至 [Kubeflow](https://www.kubeflow.org/docs/about/kubeflow/)。 NNI 支持基于 Kubeflow 的 Kubenetes，以及[Azure Kubernetes](https://azure.microsoft.com/en-us/services/kubernetes-service/)。
+    - **kubeflow** 提交任务至 [Kubeflow](https://www.kubeflow.org/docs/about/kubeflow/)。 NNI 支持基于 Kubeflow 的 Kubenetes，以及[Azure Kubernetes](https://azure.microsoft.com/en-us/services/kubernetes-service/)。 详情参考 [Kubeflow 文档](../TrainingService/KubeflowMode.md)
 
 - **searchSpacePath**
   
@@ -204,6 +216,18 @@ machineList:
     
     注意: 如果设置了 useAnnotation=True，searchSpacePath 字段必须被删除。
 
+- **multiPhase**
+  
+  - 说明
+    
+    **multiPhase** 启用[多阶段 Experiment](../AdvancedFeature/MultiPhase.md)。
+
+- **multiThread**
+  
+  - 说明
+    
+    **multiThread** 如果 multiThread 设为 `true`，可启动 Dispatcher 的多线程模式。Dispatcher 会为来自 NNI 管理器的每个命令启动一个线程。
+
 - **nniManagerIp**
   
   - 说明
@@ -266,7 +290,7 @@ machineList:
   
   - **gpuNum**
     
-        __gpuNum__ 指定了运行 Tuner 进程的 GPU 数量。 此字段的值必须是正整数。
+        __gpuNum__ 指定了运行 Tuner 进程的 GPU 数量。 此字段的值必须是正整数。 如果此字段没有设置，NNI不会在脚本中添加 `CUDA_VISIBLE_DEVICES` （也就是说，不会通过 `CUDA_VISIBLE_DEVICES` 来控制 GPU 在 Trial 中是否可见），也不会管理 GPU 资源。
         
         注意: 只能使用一种方法来指定 Tuner，例如：设置 {tunerName, optimizationMode} 或 {tunerCommand, tunerCwd}，不能同时设置两者。
         
@@ -290,7 +314,7 @@ machineList:
     
     - **classArgs**
       
-      **classArgs** 指定了 Assessor 算法的参数
+      **classArgs** 指定了 Assessor 算法的参数。
   
   - **codeDir**, **classFileName**, **className** 和 **classArgs**
     

docs/zh_CN/HowToDebug.md → docs/zh_CN/Tutorial/HowToDebug.md

@@ -2,14 +2,14 @@
 
 ## 概述
 
-NNI 中的日志分为三部分。 包括 NNI Manager， Dispatcher 以及 Trial。 这里会简单介绍这些组件。 更多信息可参考[概述](Overview.md)。
+NNI 中的日志分为三部分。 包括 NNI Manager， Dispatcher 以及 Trial。 这里会简单介绍这些组件。 更多信息可参考[概述](../Overview.md)。
 
 - **NNI Controller**：NNI Controller (nnictl) 是命令行工具，用来管理 Experiments（如：启动 Experiment）。
-- **NNI Manager**：这是 NNI 的核心。当 Experiment 出现严重错误时，从它的日志中才能找到原因。（例如，Web 界面无法打开，或者训练服务失败）
+- **NNI Manager**：这是 NNI 的核心。当 Experiment 出现严重错误时，从它的日志中才能找到原因。（例如，Web 界面无法打开，或者训练平台失败）
 - **Dispatcher**: Dispatcher 调用 **Tuner** 和 **Assessor** 的方法。 它的日志与 Tuner 和 Assessor 代码有关。 
     - **Tuner**: Tuner 是一个自动机器学习算法，会为下一个 Trial 生成新的配置。 新的 Trial 会使用这组配置来运行。
     - **Assessor**：Assessor 分析 Trial 的中间结果（例如，测试数据集上定期的精度），来确定 Trial 是否应该被提前终止。
-- **Trial**：Trial 的代码是用户编写的代码，每次 Trial 运行时会尝试一组新的配置（例如，一组新的超参值，或者某个神经网络结构）。
+- **Trial**：Trial 的代码是用户实现的代码，每次 Trial 运行时会尝试一组新的配置（例如，一组新的超参值，或者某个神经网络结构）。
 
 ## 日志的位置
 
@@ -53,7 +53,7 @@ NNI 中有不同的错误类型。 根据严重程度，可分为三类。 当 N
 
 以后一种情况为例。 某自定义的 Tuner，*\_init*\_ 函数有名为 `optimize_mode` 的参数，但配置文件中没有提供此参数。NNI 就会因为初始化 Tuner 失败而造成 Experiment 失败。 可在 Web 界面看到如下错误：
 
-![](../img/dispatcher_error.jpg)
+![](../../img/dispatcher_error.jpg)
 
 可以看到这是一个 Dispatcher 的错误。 因此，检查 Dispatcher 的日志，可找到如下信息：
 
@@ -77,6 +77,6 @@ NNI 中有不同的错误类型。 根据严重程度，可分为三类。 当 N
 
 如，其中常见的一种错误是在运行 MNIST 示例时没有安装 TensorFlow。 因为导入模块的错误（没有安装 Tensorflow，但在 Trial 代码中有 import tensorflow 的语句），每次 Trial 都会运行失败。
 
-![](../img/trial_error.jpg)
+![](../../img/trial_error.jpg)
 
 如图，每个 Trial 都有日志路径，可以从中找到 Trial 的日志和 stderr。
\ No newline at end of file

docs/zh_CN/HowToUseDocker.md → docs/zh_CN/Tutorial/HowToUseDocker.md

@@ -51,7 +51,7 @@
 
 ## 在远程平台上运行docker
 
-NNI支持在[远程平台](RemoteMachineMode.md)上启动实验，在远程机器里运行任务。 因为docker可以运行独立的Ubuntu系统和SSH服务，因此docker容器可以作为远程平台来运行NNI.
+NNI支持在[远程平台](../TrainingService/RemoteMachineMode.md)上启动实验，在远程机器里运行任务。 因为docker可以运行独立的Ubuntu系统和SSH服务，因此docker容器可以作为远程平台来运行NNI.
 
 ### 步骤1：设置docker环境
 
@@ -82,7 +82,7 @@ SSH容器需要一个端口，你需要把docker的SSH服务端口暴露给NNI
 
 ### 步骤三：运行NNI实验
 
-你可以在你的配置文件中，设置训练平台为远程平台，然后设置`machineList`配置。[参考](RemoteMachineMode.md)。 注意你应该设置正确的`port`，`username`, `passwd`或者`sshKeyPath`。
+你可以在你的配置文件中，设置训练平台为远程平台，然后设置`machineList`配置。[参考](../TrainingService/RemoteMachineMode.md)。 注意你应该设置正确的`port`，`username`, `passwd`或者`sshKeyPath`。
 
 `port`: 主机的端口，映射到docker的SSH端口中。
 

docs/zh_CN/Installation.md → docs/zh_CN/Tutorial/Installation.md

@@ -88,13 +88,13 @@
 
 ## 更多
 
-* [概述](Overview.md)
+* [概述](../Overview.md)
 * [使用命令行工具 nnictl](Nnictl.md)
 * [使用 NNIBoard](WebUI.md)
 * [定制搜索空间](SearchSpaceSpec.md)
 * [配置 Experiment](ExperimentConfig.md)
-* [如何在本机运行 Experiment (支持多 GPU 卡)？](LocalMode.md)
-* [如何在多机上运行 Experiment？](RemoteMachineMode.md)
-* [如何在 OpenPAI 上运行 Experiment？](PaiMode.md)
-* [如何通过 Kubeflow 在 Kubernetes 上运行 Experiment？](KubeflowMode.md)
-* [如何通过 FrameworkController 在 Kubernetes 上运行 Experiment？](FrameworkControllerMode.md)
+* [如何在本机运行 Experiment (支持多 GPU 卡)？](../TrainingService/LocalMode.md)
+* [如何在多机上运行 Experiment？](../TrainingService/RemoteMachineMode.md)
+* [如何在 OpenPAI 上运行 Experiment？](../TrainingService/PaiMode.md)
+* [如何通过 Kubeflow 在 Kubernetes 上运行 Experiment？](../TrainingService/KubeflowMode.md)
+* [如何通过 FrameworkController 在 Kubernetes 上运行 Experiment？](../TrainingService/FrameworkControllerMode.md)
\ No newline at end of file

docs/zh_CN/Nnictl.md → docs/zh_CN/Tutorial/Nnictl.md

@@ -114,15 +114,15 @@ nnictl 支持的命令：
 * 用法
   
   ```bash
-  nnictl stop [OPTIONS]
+  nnictl stop [Options]
   ```
 
 * 选项
   
   | 参数及缩写      | 是否必需  | 默认值 | 说明                               |
-  | ----------- | ----- | --- | -------------------------------- |
-  | id          | 否 |     | 要停止的 Experiment 标识               |
-  | --port, -p  | 否 |     | 要停止的 Experiment 使用的 RESTful 服务端口 |
+  | ---------- | ----- | --- | -------------------------------- |
+  | id         | False |     | 要停止的 Experiment 标识               |
+  | --port, -p | False |     | 要停止的 Experiment 使用的 RESTful 服务端口 |
 
 * 详细信息及样例
   
@@ -139,11 +139,13 @@ nnictl 支持的命令：
         nnictl stop [experiment_id]
         ```
         
-  3. 如果指定了端口，并且有运行中的 Experiment 正在使用该端口，那么这个 Experiment 将会停止。
+  
+  3. 如果指定了端口，并且此端口有正在运行的 Experiment，则会停止此 Experiment。
     
         ```bash
         nnictl stop --port 8080
-        ````
+        ```
+        
   
   4. 可使用 'nnictl stop all' 来停止所有的 Experiment。
     
@@ -386,9 +388,15 @@ nnictl 支持的命令：
   * 用法
     
     ```bash
-    nnictl experiment list
+    nnictl experiment list [OPTIONS]
     ```
   
+  * 选项
+  
+  | 参数及缩写 | 是否必需  | 默认值 | 说明              |
+  | ----- | ----- | --- | --------------- |
+  | --all | False |     | 列出所有 Experiment |
+
 * **nnictl experiment delete**
   
   * 说明
@@ -404,8 +412,9 @@ nnictl 支持的命令：
   * 选项
   
   | 参数及缩写 | 是否必需  | 默认值 | 说明              |
-  | ----- | ----- | --- | ------------- |
+  | ----- | ----- | --- | --------------- |
   | id    | False |     | Experiment ID   |
+  | --all | False |     | 删除所有 Experiment |
 
 <a name="export"></a>
 
@@ -474,7 +483,7 @@ nnictl 支持的命令：
     
     当前，以下 Tuner 和 Advisor 支持导入数据：
     
-    ```yml
+    ```yaml
     内置 Tuner: TPE, Anneal, GridSearch, MetisTuner
     内置 Advisor: BOHB
     ```

docs/zh_CN/QuickStart.md → docs/zh_CN/Tutorial/QuickStart.md

@@ -54,18 +54,17 @@ if __name__ == '__main__':
 
 NNI 用来帮助超参调优。它的流程如下：
 
-```pseudo
-输入: 搜索空间, Trial 代码, 配置文件
-输出: 一组最佳的超参配置
-
-1: For t = 0, 1, 2, ..., maxTrialNum,
-2:      hyperparameter = 从搜索空间选择一组参数
-3:      final result = run_trial_and_evaluate(hyperparameter)
-4:      返回最终结果给 NNI
-5:      If 时间达到上限,
-6:          停止实验
-7: return 最好的实验结果
-```
+    输入: 搜索空间, Trial 代码, 配置文件
+    输出: 一组最佳的超参配置
+    
+    1: For t = 0, 1, 2, ..., maxTrialNum,
+    2:      hyperparameter = 从搜索空间选择一组参数
+    3:      final result = run_trial_and_evaluate(hyperparameter)
+    4:      返回最终结果给 NNI
+    5:      If 时间达到上限,
+    6:          停止实验
+    7: return 最好的实验结果
+    
 
 如果需要使用 NNI 来自动训练模型，找到最佳超参，需要如下三步：
 
@@ -208,28 +207,28 @@ Web 地址为：[IP 地址]:8080
 
 Experiment 相关信息会显示在界面上，配置和搜索空间等。 可通过 **Download** 按钮来`下载信息和参数`。 可以在运行中或结束后，随时下载 Experiment 的结果。
 
-![](../img/QuickStart1.png)
+![](../../img/QuickStart1.png)
 
 前 10 个 Trial 结果也会列在 Overview 页面中，可以在 "Trials Detail" 部分浏览所有的 Trial。
 
-![](../img/QuickStart2.png)
+![](../../img/QuickStart2.png)
 
 #### 查看 Trial 详情页面
 
 点击 "Default Metric" 来查看所有 Trial 的点图。 悬停鼠标来查看默认指标和搜索空间信息。
 
-![](../img/QuickStart3.png)
+![](../../img/QuickStart3.png)
 
 点击 "Hyper Parameter" 标签查看图像。
 
 * 可选择百分比查看最好的 Trial。
 * 选择两个轴来交换位置。
 
-![](../img/QuickStart4.png)
+![](../../img/QuickStart4.png)
 
 点击 "Trial Duration" 标签来查看柱状图。
 
-![](../img/QuickStart5.png)
+![](../../img/QuickStart5.png)
 
 下面是所有 Trial 的状态。 包括：
 
@@ -238,20 +237,20 @@ Experiment 相关信息会显示在界面上，配置和搜索空间等。 可
 * Kill: 可终止正在运行的任务。
 * 支持搜索某个特定的 Trial。
 
-![](../img/QuickStart6.png)
+![](../../img/QuickStart6.png)
 
 * 中间结果图
 
-![](../img/QuickStart7.png)
+![](../../img/QuickStart7.png)
 
 ## 相关主题
 
-* [尝试不同的 Tuner](BuiltinTuner.md)
-* [尝试不同的 Assessor](BuiltinAssessors.md)
+* [尝试不同的 Tuner](../Tuner/BuiltinTuner.md)
+* [尝试不同的 Assessor](../Assessor/BuiltinAssessor.md)
 * [使用命令行工具 nnictl](Nnictl.md)
-* [如何编写 Trial 代码](Trials.md)
-* [如何在本机运行 Experiment (支持多 GPU 卡)？](LocalMode.md)
-* [如何在多机上运行 Experiment？](RemoteMachineMode.md)
-* [如何在 OpenPAI 上运行 Experiment？](PaiMode.md)
-* [如何通过 Kubeflow 在 Kubernetes 上运行 Experiment？](KubeflowMode.md)
-* [如何通过 FrameworkController 在 Kubernetes 上运行 Experiment？](FrameworkControllerMode.md)
+* [如何实现 Trial 代码](../TrialExample/Trials.md)
+* [如何在本机运行 Experiment (支持多 GPU 卡)？](../TrainingService/LocalMode.md)
+* [如何在多机上运行 Experiment？](../TrainingService/RemoteMachineMode.md)
+* [如何在 OpenPAI 上运行 Experiment？](../TrainingService/PaiMode.md)
+* [如何通过 Kubeflow 在 Kubernetes 上运行 Experiment？](../TrainingService/KubeflowMode.md)
+* [如何通过 FrameworkController 在 Kubernetes 上运行 Experiment？](../TrainingService/FrameworkControllerMode.md)
\ No newline at end of file

docs/zh_CN/SearchSpaceSpec.md → docs/zh_CN/Tutorial/SearchSpaceSpec.md

@@ -47,7 +47,8 @@
 
 * {"_type":"quniform","_value":[low, high, q]}
   
-  * 这表示变量值会类似于 round(uniform(low, high) / q) * q
+  * 变量值为 clip(round(uniform(low, high) / q) * q, low, high)，clip 操作用于约束生成值的边界。 例如，_value 为 [0, 10, 2.5]，可取的值为 [0, 2.5, 5.0, 7.5, 10.0]; _value 为 [2, 10, 5]，可取的值为 [2, 5, 10]。
+  
   * 适用于离散，同时反映了某种"平滑"的数值，但上下限都有限制。 如果需要从范围 [low, high] 中均匀选择整数，可以如下定义 `_value`：`[low, high, 1]`。
 
 * {"_type":"loguniform","_value":[low, high]}
@@ -57,7 +58,7 @@
 
 * {"_type":"qloguniform","_value":[low, high, q]}
   
-  * 这表示变量值会类似于 round(loguniform(low, high)) / q) * q
+  * 变量值为 clip(round(loguniform(low, high) / q) * q, low, high)，clip 操作用于约束生成值的边界。
   * 适用于值是“平滑”的离散变量，但上下限均有限制。
 
 * {"_type":"normal","_value":[mu, sigma]}
@@ -78,6 +79,12 @@
   * 这表示变量值会类似于 round(exp(normal(mu, sigma)) / q) * q
   * 适用于值是“平滑”的离散变量，但某一边有界。
 
+* {"_type":"mutable_layer","_value":{mutable_layer_infomation}}
+  
+  * [神经网络架构搜索空间](../AdvancedFeature/GeneralNasInterfaces.md)的类型。 值是字典类型，键值对表示每个 mutable_layer 的名称和搜索空间。
+  * 当前，只能通过 Annotation 来使用这种类型的搜索空间。因此不需要为搜索空间定义 JSON 文件，它会通过 Trial 中的 Annotation 自动生成。
+  * 具体用法参考[通用 NAS 接口](../AdvancedFeature/GeneralNasInterfaces.md)。
+
 ## 每种 Tuner 支持的搜索空间类型
 
 |                     |  choice  | randint  | uniform  | quniform | loguniform | qloguniform |  normal  | qnormal  | lognormal | qlognormal |
@@ -88,24 +95,16 @@
 |   Evolution Tuner   | ✓ | ✓ | ✓ | ✓ |  ✓  |  ✓   | ✓ | ✓ | ✓  |  ✓  |
 |     SMAC Tuner      | ✓ | ✓ | ✓ | ✓ |  ✓  |             |          |          |           |            |
 |     Batch Tuner     | ✓ |          |          |          |            |             |          |          |           |            |
-|  Grid Search Tuner  | ✓ |          |          | ✓ |            |  ✓   |          |          |           |            |
+|  Grid Search Tuner  | ✓ | ✓ |          | ✓ |            |             |          |          |           |            |
 |  Hyperband Advisor  | ✓ | ✓ | ✓ | ✓ |  ✓  |  ✓   | ✓ | ✓ | ✓  |  ✓  |
 |     Metis Tuner     | ✓ | ✓ | ✓ | ✓ |            |             |          |          |           |            |
 |      GP Tuner       | ✓ | ✓ | ✓ | ✓ |  ✓  |  ✓   |          |          |           |            |
 
 已知的局限：
 
-* 注意，在 Grid Search Tuner 中，为了使用方便 `quniform` 和 `qloguniform` 的定义也有所改变，其中的 q 表示采样值的数量。 详情如下：
-  
-      * 类型 'quniform' 接收三个值 [low, high, q]， 其中 [low, high] 指定了范围，而 'q' 指定了会被均匀采样的值的数量。 注意 q 至少为 2。 它的第一个采样值为 'low'，每个采样值都会比前一个大 (high-low)/q 。
-      
-      * 类型 'qloguniform' 的行为与 'quniform' 类似，不同处在于首先将范围改为 [log(low), log(high)] 采样后，再将数值还原。
-      
-
 * 注意 Metis Tuner 当前仅支持在 `choice` 中使用数值。
 
 * 请注意，对于嵌套搜索空间：
   
       * 只有 随机搜索/TPE/Anneal/Evolution Tuner 支持嵌套搜索空间
-      
-      * 不支持嵌套搜索空间 "超参" 并行图，对其的改进通过 #1110(https://github.com/microsoft/nni/issues/1110) 来跟踪 。欢迎任何建议和贡献。
+      * 不支持嵌套搜索空间 "超参" 的可视化，对其的改进通过 #1110(https://github.com/microsoft/nni/issues/1110) 来跟踪 。欢迎任何建议和贡献。
\ No newline at end of file
\ No newline at end of file

docs/zh_CN/SetupNniDeveloperEnvironment.md → docs/zh_CN/Tutorial/SetupNniDeveloperEnvironment.md

@@ -4,7 +4,7 @@
 
 ## 调试 NNI 源代码的最佳实践
 
-要调试 NNI 源代码，需要 Ubuntu 16.04 或更高版本系统的开发环境，并需要安装 Python 3.x 以及 pip3，然后遵循以下步骤。
+要调试 NNI 源代码，需要 Ubuntu 16.04 或更高版本系统的开发环境，并需要安装 Python 3 以及 pip 3，然后遵循以下步骤。
 
 **1. 克隆源代码**
 
@@ -57,4 +57,4 @@ Trial 启动 Experiment 来检查环境。 例如，运行命令
 
 * * *
 
-最后，希望一切顺利。 参考[贡献](./Contributing.md)文档，来了解更多创建拉取请求或问题的指南。
+最后，希望一切顺利。 参考[贡献](Contributing.md)文档，来了解更多创建拉取请求或问题的指南。
\ No newline at end of file