Merge pull request #206 from microsoft/master

merge master

docs/zh_CN/CommunitySharings/community_sharings.rst

@@ -8,6 +8,7 @@
     :maxdepth: 2
 
     Recommenders 中使用 NNI<RecommendersSvd>
+    使用 NNI 为 SPTAG 自动调参 <SptagAutoTune>
     神经网络结构搜索（NAS）的对比<NasComparision>
     超参调优算法的对比<HpoComparision>
     TPE 的并行优化<ParallelizingTpeSearch>

docs/zh_CN/Release_v1.0.md

+<p align="center">
+<img src=".././img/release-1-title-1.png" width="100%" />
+</p>
+
+从 2018 年 9 月到 2019 年 9 月，我们一直在前进 ...
+
+**好消息！**&nbsp;&nbsp;NNI v1.0 带来了更强的**伸缩性**和**易用性**。 基于各种[调参算法](./Tuner/BuiltinTuner.md)，NNI 已经支持了超参调优，神经网络结构搜索，自动特侦工程等，对算法工程师非常有用的功能。除此之外，NNI v1.0 带来了大量的改进，包括调优算法的优化，[Web 界面简化并更加直观](./Tutorial/WebUI.md)，以及[更多样的平台](./TrainingService/SupportTrainingService.md)。 NNI 已经成为了一个更加智能的自动机器学习（AutoML）工具包。
+
+  
+  
+  
+
+<p align="center">
+<img src=".././img/nni-1.png" width="80%" />
+</p>
+
+  
+  
+
+<p align="center">
+<img src=".././img/release-1-title-2.png" width="100%" />
+</p>
+
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;**第一步**： 根据[教程](./Tutorial/Installation.md)安装 NNI v1.0。  
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;**第二步**：找到 "Hello world" 示例，按照[教程](./Tutorial/QuickStart.md)入门。   
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;**第三步**：熟悉 [Web 界面](./Tutorial/WebUI.md)，用 NNI 进行自动机器学习！  
+
+
+全自动工具极大地提高了调优过程的效率。 关于 v1.0 的更多细节，可参考 [Release 1.0](https://github.com/microsoft/nni/releases)。 关于进一步计划，可参考[路线图](https://github.com/microsoft/nni/wiki/Roadmap)。 此外，欢迎更多的参与者加入我们。可参考[如何贡献](./Tutorial/Contributing.md)，来了解多种参与方法。
\ No newline at end of file

docs/zh_CN/SupportedFramework_Library.md

+# 框架和库的支持
+
+通过内置的 Python API，NNI 天然支持所有 Python (` 版本 >= 3.5`) 语言的 AI 框架，可使用所有超参调优和神经网络搜索算法。 NNI 还为常见场景提供了一些示例和教程，使上手更容易。
+
+## 支持的 AI 框架
+
+* **[PyTorch]** https://github.com/pytorch/pytorch
+
+* [MNIST-pytorch](../../examples/trials/mnist-distributed-pytorch)  
+    
+* [CIFAR-10](TrialExample/Cifar10Examples.md)  
+    
+* [TGS salt identification chanllenge](../../examples/trials/kaggle-tgs-salt/README_zh_CN.md)  
+    
+* [Network morphism](../../examples/trials/network_morphism/README_zh_CN.md)  
+    
+
+* **[TensorFlow]** https://github.com/tensorflow/tensorflow
+
+* [MNIST-tensorflow](../../examples/trials/mnist-distributed)  
+    
+* [Squad](../../examples/trials/ga_squad/README_zh_CN.md)  
+    
+
+* **[Keras]** https://github.com/keras-team/keras
+
+* [MNIST-keras](../../examples/trials/mnist-keras)  
+    
+* [Network morphism](../../examples/trials/network_morphism/README_zh_CN.md)  
+    
+
+* **[MXNet]** https://github.com/apache/incubator-mxnet
+* **[Caffe2]** https://github.com/BVLC/caffe
+* **[CNTK (Python 语言)]** https://github.com/microsoft/CNTK
+* **[Spark MLlib]** http://spark.apache.org/mllib/
+* **[Chainer]** https://chainer.org/
+* **[Theano]** https://pypi.org/project/Theano/   
+    
+
+如果能[贡献更多示例](Tutorial/Contributing.md)，会对其他 NNI 用户有很大的帮助。
+
+## 支持的库
+
+NNI 也支持其它 Python 库，包括一些基于 GBDT 的算法：XGBoost, CatBoost 以及 lightGBM。
+
+* **[Scikit-learn]** https://scikit-learn.org/stable/
+
+* [Scikit-learn](TrialExample/SklearnExamples.md)  
+    
+
+* **[XGBoost]** https://xgboost.readthedocs.io/en/latest/
+* **[CatBoost]** https://catboost.ai/
+* **[LightGBM]** https://lightgbm.readthedocs.io/en/latest/
+
+* [Auto-gbdt](TrialExample/GbdtExample.md)  
+    
+
+这只是 NNI 支持的一小部分库。 如果对 NNI 感兴趣，可参考[教程](TrialExample/Trials.md)来继续学习。
+
+除了这些案例，也欢迎更多的用户将 NNI 应用到自己的工作中，如果有任何疑问，请参考[实现 Trial](TrialExample/Trials.md)。 如果想成为 NNI 的贡献者，无论是分享示例，还是实现 Tuner 或其它内容，我们都非常期待您的参与。更多信息请[参考这里](Tutorial/Contributing.md)。
\ No newline at end of file

docs/zh_CN/TrainingService/LocalMode.md

@@ -57,7 +57,7 @@
     }
     
 
-参考 [SearchSpaceSpec.md](../Tutorial/SearchSpaceSpec.md) 进一步了解搜索空间。
+参考[定义搜索空间](../Tutorial/SearchSpaceSpec.md)进一步了解。
 
 > 第三步：定义 Experiment
 > 

docs/zh_CN/TrainingService/PaiMode.md

@@ -57,7 +57,36 @@ paiConfig:
 * shmMB 
     * 可选。 设置 OpenPAI 的 shmMB，即 Docker 中的共享内存。
 * authFile 
-    * 可选，设置在使用 OpenPAI 时的私有 Docker 认证文件路径。[参考文档](https://github.com/microsoft/pai/blob/2ea69b45faa018662bc164ed7733f6fdbb4c42b3/docs/faq.md#q-how-to-use-private-docker-registry-job-image-when-submitting-an-openpai-job)。
+    * 可选。在使用 pai 模式时，为私有 Docker 仓库设置认证文件，[见参考文档](https://github.com/microsoft/pai/blob/2ea69b45faa018662bc164ed7733f6fdbb4c42b3/docs/faq.md#q-how-to-use-private-docker-registry-job-image-when-submitting-an-openpai-job)。提供 authFile 的本地路径即可， NNI 会上传此文件。
+
+* portList
+    
+    * 可选。 设置 OpenPAI 的 portList。指定了容器中使用的端口列表，[参考文档](https://github.com/microsoft/pai/blob/b2324866d0280a2d22958717ea6025740f71b9f0/docs/job_tutorial.md#specification)。  
+        示例如下：
+        portList:
+          - label: test
+            beginAt: 8080
+            portNumber: 2
+        
+    
+    假设需要在 MNIST 示例中使用端口来运行 TensorBoard。 第一步是编写 `mnist.py` 的包装脚本 `launch_pai.sh`。
+    
+    ```bash
+    export TENSORBOARD_PORT=PAI_PORT_LIST_${PAI_CURRENT_TASK_ROLE_NAME}_0_tensorboard
+    tensorboard --logdir . --port ${!TENSORBOARD_PORT} &
+    python3 mnist.py
+    ```
+    
+    portList 的配置部分如下：
+    
+    ```yaml
+    trial:
+    command: bash launch_pai.sh
+    portList:
+      - label: tensorboard
+        beginAt: 0
+        portNumber: 1
+    ```
 
 完成并保存 NNI Experiment 配置文件后（例如可保存为：exp_pai.yml），运行以下命令：
 

docs/zh_CN/TrainingService/SupportTrainingService.md

+# 训练平台
+
+NNI 为 Trial 任务实现了训练平台。 NNI 支持[本机](./LocalMode.md), [远程](./RemoteMachineMode.md), [OpenPAI](./PaiMode.md), [Kubeflow](./KubeflowMode.md) 和 [FrameworkController](./FrameworkControllerMode.md) 这些内置的训练平台。  
+NNI 不仅提供了这些内置的训练平台，还提供了轻松连接自己训练平台的方法。
+
+## 内置训练平台
+
+| 训练平台                                                    | 简介                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [**本机**](./LocalMode.md)                                | NNI 支持在本机运行实验，称为 local 模式。 local 模式表示 NNI 会在运行 NNI Manager 进程计算机上运行 Trial 任务，支持 GPU 调度功能。                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| [**远程计算机**](./RemoteMachineMode.md)                     | NNI 支持通过 SSH 通道在多台计算机上运行 Experiment，称为 remote 模式。 NNI 需要这些计算机的访问权限，并假定已配置好了深度学习训练环境。 NNI 将在远程计算机上中提交 Trial 任务，并根据 GPU 资源调度 Trial 任务。                                                                                                                                                                                                                                                                                                                                                                                                   |
+| [**OpenPAI**](./PaiMode.md)                             | NNI 支持在 [OpenPAI](https://github.com/Microsoft/pai) （简称 pai）上运行 Experiment，即 pai 模式。 在使用 NNI 的 pai 模式前, 需要有 [OpenPAI](https://github.com/Microsoft/pai) 群集及其账户。 如果没有 OpenPAI，参考[这里](https://github.com/Microsoft/pai#how-to-deploy)来进行部署。 在 pai 模式中，会在 Docker 创建的容器中运行 Trial 程序。                                                                                                                                                                                                                                                       |
+| [**Kubeflow**](./KubeflowMode.md)                       | NNI 支持在 [Kubeflow](https://github.com/kubeflow/kubeflow)上运行，称为 kubeflow 模式。 在开始使用 NNI 的 Kubeflow 模式前，需要有一个 Kubernetes 集群，可以是私有部署的，或者是 [Azure Kubernetes Service(AKS)](https://azure.microsoft.com/zh-cn/services/kubernetes-service/)，并需要一台配置好 [kubeconfig](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) 的 Ubuntu 计算机连接到此 Kubernetes 集群。 如果不熟悉 Kubernetes，可先浏览[这里](https://kubernetes.io/docs/tutorials/kubernetes-basics/)。 在 kubeflow 模式下，每个 Trial 程序会在 Kubernetes 集群中作为一个 Kubeflow 作业来运行。 |
+| [**FrameworkController**](./FrameworkControllerMode.md) | NNI 支持使用 [FrameworkController](https://github.com/Microsoft/frameworkcontroller)，来运行 Experiment，称之为 frameworkcontroller 模式。 FrameworkController 构建于 Kubernetes 上，用于编排各种应用。这样，可以不用为某个深度学习框架安装 Kubeflow 的 tf-operator 或 pytorch-operator 等。 而直接用 FrameworkController 作为 NNI Experiment 的训练平台。                                                                                                                                                                                                                                            |
+
+
+## 实现训练平台
+
+TrainingService 在设计上为了便于实现，将平台相关的公共属性抽象成类。用户只需要继承这个抽象类，并根据平台特点实现子类，便能够实现 TrainingService。  
+TrainingService 的声明如下：
+
+    abstract class TrainingService {
+        public abstract listTrialJobs(): Promise<TrialJobDetail[]>;
+        public abstract getTrialJob(trialJobId: string): Promise<TrialJobDetail>;
+        public abstract addTrialJobMetricListener(listener: (metric: TrialJobMetric) => void): void;
+        public abstract removeTrialJobMetricListener(listener: (metric: TrialJobMetric) => void): void;
+        public abstract submitTrialJob(form: JobApplicationForm): Promise<TrialJobDetail>;
+        public abstract updateTrialJob(trialJobId: string, form: JobApplicationForm): Promise<TrialJobDetail>;
+        public abstract get isMultiPhaseJobSupported(): boolean;
+        public abstract cancelTrialJob(trialJobId: string, isEarlyStopped?: boolean): Promise<void>;
+        public abstract setClusterMetadata(key: string, value: string): Promise<void>;
+        public abstract getClusterMetadata(key: string): Promise<string>;
+        public abstract cleanUp(): Promise<void>;
+        public abstract run(): Promise<void>;
+    }
+    
+
+TrainingService 的父类有一些抽象函数，用户需要继承父类并实现所有这些抽象函数。  
+有关如何实现 TrainingService 的更多信息，[参考这里](https://github.com/microsoft/nni/blob/master/docs/zh_CN/TrainingService/HowToImplementTrainingService.md)。
\ No newline at end of file

docs/zh_CN/Tuner/BuiltinTuner.md

@@ -115,6 +115,12 @@ tuner:
 
 此算法对计算资源的需求相对较高。 需要非常大的初始种群，以免落入局部最优中。 如果 Trial 时间很短，或者使用了 Assessor，就非常适合此算法。 如果 Trial 代码支持权重迁移，即每次 Trial 会从上一轮继承已经收敛的权重，建议使用此算法。 这会大大提高训练速度。 [详细说明](./EvolutionTuner.md)
 
+**参数**
+
+* **optimize_mode** (*maximize 或 minimize, 可选项, 默认值为 maximize*) - 如果为 'maximize'，表示 Tuner 的目标是将指标最大化。 如果为 'minimize'，表示 Tuner 的目标是将指标最小化。
+
+* **population_size** (*int 类型(大于 0), 可选项, 默认值为 20*) - 表示遗传 Tuner 中的种群（Trial 数量）。
+
 **示例**
 
 ```yaml
@@ -123,6 +129,7 @@ tuner:
   builtinTunerName: Evolution
   classArgs:
     optimize_mode: maximize
+    population_size: 100
 ```
 
 <br />

docs/zh_CN/Tuner/GridsearchTuner.md

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

docs/zh_CN/Tutorial/ExperimentConfig.md

 # Experiment（实验）配置参考
 
-创建 Experiment 时，需要给 nnictl 命令提供配置文件的路径。 配置文件是 YAML 格式，需要保证其格式正确。 本文介绍了配置文件的内容，并提供了一些示例和模板。
+创建 Experiment 所需要的配置文件。 配置文件的路径会传入 `nnictl` 命令。 配置文件的格式为 YAML。 本文介绍了配置文件的内容，并提供了一些示例和模板。
 
 - [Experiment（实验）配置参考](#Experiment-config-reference) 
   - [模板](#Template)
@@ -550,6 +550,10 @@ machineList:
       
       **azureShare** 是 Azure 文件存储的共享参数。
   
+  - **uploadRetryCount**
+    
+    如果上传文件至 Azure Storage 失败，NNI 会重试。此字段指定了重试的次数。
+
 - **paiConfig**
   
   - **userName**

docs/zh_CN/Tutorial/Nnictl.md

@@ -123,6 +123,7 @@ nnictl 支持的命令：
   | ---------- | ----- | --- | -------------------------------- |
   | id         | False |     | 要停止的 Experiment 标识               |
   | --port, -p | False |     | 要停止的 Experiment 使用的 RESTful 服务端口 |
+  | --all, -a  | False |     | 停止所有 Experiment                  |
 
 * 详细信息及样例
   
@@ -147,10 +148,10 @@ nnictl 支持的命令：
         ```
         
   
-  4. 可使用 'nnictl stop all' 来停止所有的 Experiment。
+  4. 可使用 'nnictl stop --all' 来停止所有的 Experiment。
     
         ```bash
-        nnictl stop all
+        nnictl stop --all
         ```
         
   

docs/zh_CN/Tutorial/SearchSpaceSpec.md

@@ -10,11 +10,11 @@
 
 ```yaml
 {
-    "dropout_rate":{"_type":"uniform","_value":[0.1,0.5]},
-    "conv_size":{"_type":"choice","_value":[2,3,5,7]},
-    "hidden_size":{"_type":"choice","_value":[124, 512, 1024]},
-    "batch_size":{"_type":"choice","_value":[50, 250, 500]},
-    "learning_rate":{"_type":"uniform","_value":[0.0001, 0.1]}
+    "dropout_rate": {"_type": "uniform", "_value": [0.1, 0.5]},
+    "conv_size": {"_type": "choice", "_value": [2, 3, 5, 7]},
+    "hidden_size": {"_type": "choice", "_value": [124, 512, 1024]},
+    "batch_size": {"_type": "choice", "_value": [50, 250, 500]},
+    "learning_rate": {"_type": "uniform", "_value": [0.0001, 0.1]}
 }
 
 ```
@@ -25,61 +25,60 @@
 
 所有采样策略和参数如下：
 
-* {"_type":"choice","_value":options}
+* `{"_type": "choice", "_value": options}`
   
-  * 表示变量的值是选项之一。 这里的 'options' 是一个数组。 选项的每个元素都是字符串。 也可以是嵌套的子搜索空间。此子搜索空间仅在相应的元素选中后才起作用。 该子搜索空间中的变量可看作是条件变量。
-  
-  * [nested] 搜索空间定义的简单[示例](https://github.com/microsoft/nni/tree/master/examples/trials/mnist-nested-search-space/search_space.json)。 如果选项列表中的元素是 dict，则它是一个子搜索空间，对于内置的 Tuner，必须在此 dict 中添加键 “_name”，这有助于标识选中的元素。 相应的，这是使用从 NNI 获得的嵌套搜索空间的[示例](https://github.com/microsoft/nni/tree/master/examples/trials/mnist-nested-search-space/sample.json)。 以下 Tuner 支持嵌套搜索空间：
+  * 表示变量的值是选项之一。 这里的 `options` 应该是字符串或数值的列表。 可将任意对象（如子数组，数字与字符串的混合值或者空值）存入此数组中，但可能会产生不可预料的行为。
+  * `options` 也可以是嵌套的子搜索空间。此子搜索空间仅在相应的元素选中后才起作用。 该子搜索空间中的变量可看作是条件变量。 <a [嵌套搜索空间的简单示例](https://github.com/microsoft/nni/tree/master/examples/trials/mnist-nested-search-space/search_space.json)。 如果选项列表中的元素是 dict，则它是一个子搜索空间，对于内置的 Tuner，必须在此 dict 中添加键 `_name`，这有助于标识选中的元素。 相应的，这是使用从 NNI 获得的嵌套搜索空间的[示例](https://github.com/microsoft/nni/tree/master/examples/trials/mnist-nested-search-space/sample.json)。 以下 Tuner 支持嵌套搜索空间：
     
     * Random Search（随机搜索） 
     * TPE
     * Anneal（退火算法）
     * Evolution
 
-* {"_type":"randint","_value":[lower, upper]}
+* `{"_type": "randint", "_value": [lower, upper]}`
   
-  * 当前实现的是 "quniform" 的 "randint" 分布，随机变量的分布函数是 round(uniform(lower, upper))。 所选择值的类型是 float。 如果要使用整数，需要显式转换。
+  * 从 `lower` (包含) 到 `upper` (不包含) 中选择一个随机整数。
+  * 注意：不同 Tuner 可能对 `randint` 有不同的实现。 一些 Tuner（例如，TPE，GridSearch）将从低到高无序选择，而其它一些（例如，SMAC）则有顺序。 如果希望所有 Tuner 都有序，可使用 `quniform` 并设置 `q=1`。
 
-* {"_type":"uniform","_value":[low, high]}
+* `{"_type": "uniform", "_value": [low, high]}`
   
   * 变量是 low 和 high 之间均匀分布的值。
   * 当优化时，此变量值会在两侧区间内。
 
-* {"_type":"quniform","_value":[low, high, 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]。
+* `{"_type": "quniform", "_value": [low, high, 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]}
+* `{"_type": "loguniform", "_value": [low, high]}`
   
   * 变量值在范围 [low, high] 中是 loguniform 分布，如 exp(uniform(log(low), log(high)))，因此返回值是对数均匀分布的。
   * 当优化时，此变量必须是正数。
 
-* {"_type":"qloguniform","_value":[low, high, q]}
+* `{"_type": "qloguniform", "_value": [low, high, q]}`
   
-  * 变量值为 clip(round(loguniform(low, high) / q) * q, low, high)，clip 操作用于约束生成值的边界。
+  * 变量值为 `clip(round(loguniform(low, high) / q) * q, low, high)`，clip 操作用于约束生成值的边界。
   * 适用于值是“平滑”的离散变量，但上下限均有限制。
 
-* {"_type":"normal","_value":[mu, sigma]}
+* `{"_type": "normal", "_value": [mu, sigma]}`
   
   * 变量值为实数，且为正态分布，均值为 mu，标准方差为 sigma。 优化时，此变量不受约束。
 
-* {"_type":"qnormal","_value":[mu, sigma, q]}
+* `{"_type": "qnormal", "_value": [mu, sigma, q]}`
   
-  * 这表示变量值会类似于 round(normal(mu, sigma) / q) * q
+  * 这表示变量值会类似于 `round(normal(mu, sigma) / q) * q`
   * 适用于在 mu 周围的离散变量，且没有上下限限制。
 
-* {"_type":"lognormal","_value":[mu, sigma]}
+* `{"_type": "lognormal", "_value": [mu, sigma]}`
   
-  * 变量值为 exp(normal(mu, sigma)) 分布，范围值是对数的正态分布。 当优化时，此变量必须是正数。
+  * 变量值为 `exp(normal(mu, sigma))` 分布，范围值是对数的正态分布。 当优化时，此变量必须是正数。
 
-* {"_type":"qlognormal","_value":[mu, sigma, q]}
+* `{"_type": "qlognormal", "_value": [mu, sigma, q]}`
   
-  * 这表示变量值会类似于 round(exp(normal(mu, sigma)) / q) * q
+  * 这表示变量值会类似于 `round(exp(normal(mu, sigma)) / q) * q`
   * 适用于值是“平滑”的离散变量，但某一边有界。
 
-* {"_type":"mutable_layer","_value":{mutable_layer_infomation}}
+* `{"_type": "mutable_layer", "_value": {mutable_layer_infomation}}`
   
   * [神经网络架构搜索空间](../AdvancedFeature/GeneralNasInterfaces.md)的类型。 值是字典类型，键值对表示每个 mutable_layer 的名称和搜索空间。
   * 当前，只能通过 Annotation 来使用这种类型的搜索空间。因此不需要为搜索空间定义 JSON 文件，它会通过 Trial 中的 Annotation 自动生成。

docs/zh_CN/Tutorial/WebUI.md

@@ -12,7 +12,7 @@
 
 ![](../../img/webui-img/refresh-interval.png)
 
-* 支持查看并下载 Experiment 结果，以及 NNI Manager、Dispatcher 的日志文件。
+* "View" 按钮支持查看并下载 Experiment 结果，以及 NNI Manager、Dispatcher 的日志文件。
 
 ![](../../img/webui-img/download.png)
 
@@ -53,13 +53,11 @@
 
 ![](../../img/webui-img/trials_intermeidate.png)
 
-由于训练中可能有非常多的中间结果，因此中间结果图提供了过滤功能。 如果要使用过滤按钮查看部分 Trial，则需要提供数据。
+Trial 可能在训练过程中有大量中间结果。 为了更清楚的理解一些 Trial 的趋势，可以为中间结果图设置过滤。
 
-第一个输入框应该填入什么？ 可能会发现一个 Trial 的中间结果点变得更好或者更差。 换句话说，这可能是非常重要的中间结果点。 只需将其输入第一个输入框中。
+这样可以发现 Trial 在某个中间结果上会变得更好或更差。 换句话说，这是一个重要的中间结果。 如果要仔细查看这个点，可以在 #Intermediate 中输入其横坐标。
 
-选择了中间结果序号后，要输入需要了解的该中间结果序号的指标范围。 即其最小值和最大值。 如此图中，中间结果点为 9，指标范围为 60 至 80。
-
-Trial 中指标范围在 20 至 60 的 13 个结果就被过滤掉了。
+并输入这个中间结果的指标范围。 如下图所示，选择了第 4 个中间结果， 并将指标范围设置为了 0.8 -1。
 
 ![](../../img/webui-img/filter-intermediate.png)
 

docs/zh_CN/conf.py

@@ -28,7 +28,7 @@ author = 'Microsoft'
 # The short X.Y version
 version = ''
 # The full version, including alpha/beta/rc tags
-release = 'v0.7'
+release = 'v1.0'
 
 # -- General configuration ---------------------------------------------------
 

examples/trials/efficientnet/.gitignore

+EfficientNet-PyTorch
\ No newline at end of file

examples/trials/efficientnet/README.md

+# EfficientNet
+
+[EfficientNet: Rethinking Model Scaling for Convolutional Neural Networks](https://arxiv.org/abs/1905.11946)
+
+Provided here are: Search space and tuners for finding the best tuple (alpha, beta, gamma) for EfficientNet-B1 with grid search, as discussed in Section 3.3 in [paper](https://arxiv.org/abs/1905.11946).
+
+## Instructions
+
+1. Set your working directory here in this directory.
+2. Run `git clone https://github.com/ultmaster/EfficientNet-PyTorch` to clone this modified version of [EfficientNet-PyTorch](https://github.com/lukemelas/EfficientNet-PyTorch). The modifications were done to adhere to the original [Tensorflow version](https://github.com/tensorflow/tpu/tree/master/models/official/efficientnet) as close as possible (including EMA, label smoothing and etc.); also added are the part which gets parameters from tuner and reports intermediate/final results. Clone it into `EfficientNet-PyTorch`; the files like `main.py`, `train_imagenet.sh` will appear inside, as specified in the configuration files.
+3. Run `nnictl create --config config_net.yml` to find the best EfficientNet-B1. Adjust the training service (PAI/local/remote), batch size in the config files according to the environment.
+
+For training on ImageNet, read `EfficientNet-PyTorch/train_imagenet.sh`. Download ImageNet beforehand and extract it adhering to [PyTorch format](https://pytorch.org/docs/stable/torchvision/datasets.html#imagenet) and then replace `/mnt/data/imagenet` in with the location of the ImageNet storage. This file should also be a good example to follow for mounting ImageNet into the container on OpenPAI.
+
+## Results
+
+The follow image is a screenshot, demonstrating the relationship between acc@1 and alpha, beta, gamma.
+
+![](assets/search_result.png)
\ No newline at end of file

examples/trials/efficientnet/README_zh_CN.md

+# EfficientNet
+
+[EfficientNet: 重新思考卷积神经网络的模型尺度](https://arxiv.org/abs/1905.11946)
+
+这里提供了：使用遍历搜索为 EfficientNet-B1 找到最佳元组（alpha，beta，gamma）的搜索空间和 Tuner。参考[论文](https://arxiv.org/abs/1905.11946) 3.3。
+
+## 说明
+
+1. 设置此目录为当前目录。
+2. 运行 `git clone https://github.com/ultmaster/EfficientNet-PyTorch` 来 clone 修改过的 [EfficientNet-PyTorch](https://github.com/lukemelas/EfficientNet-PyTorch)。 修改尽可能接近原始的 [TensorFlow 版本](https://github.com/tensorflow/tpu/tree/master/models/official/efficientnet) （包括 EMA，标记平滑度等等。）；另外添加了代码从 Tuner 获取参数并回调中间和最终结果。 将其 clone 至 `EfficientNet-PyTorch`；`main.py`，`train_imagenet.sh` 等文件会在配置文件中指定的路径。
+3. 运行 `nnictl create --config config_net.yml` 来找到最好的 EfficientNet-B1。 根据环境来调整训练平台（OpenPAI、本机、远程），batch size。
+
+在 ImageNet 上的训练，可阅读 `EfficientNet-PyTorch/train_imagenet.sh`。 下载 ImageNet，并参考 [PyTorch 格式](https://pytorch.org/docs/stable/torchvision/datasets.html#imagenet) 来解压，然后将 `/mnt/data/imagenet` 替换为 ImageNet 的路径。 此文件也是如何将 ImageNet 挂载到 OpenPAI 容器的示例。
+
+## 结果
+
+下图展示了 acc@1 和 alpha、beta、gamma 之间的关系。
+
+![](assets/search_result.png)
\ No newline at end of file

examples/trials/efficientnet/config_net.yml

+authorName: unknown
+experimentName: example_efficient_net
+trialConcurrency: 8
+maxExecDuration: 48h
+maxTrialNum: 100
+trainingServicePlatform: pai
+searchSpacePath: search_net.json
+useAnnotation: false
+tuner:
+  codeDir: .
+  classFileName: tuner.py
+  className: FixedProductTuner
+  classArgs:
+    product: 2
+trial:
+  codeDir: EfficientNet-PyTorch
+  command: sh train_imagenet.sh
+  cpuNum: 4
+  memoryMB: 25000
+  shmMB: 25000
+  gpuNum: 1
+  virtualCluster: nni
+  image: msranni/nni:latest
+nniManagerIp: <nni_manager_ip>
+paiConfig:
+  userName: <username>
+  passWord: <password>
+  host: <host>

examples/trials/efficientnet/search_net.json

+{
+  "alpha": {
+    "_type": "quniform",
+    "_value": [1.0, 2.0, 0.1]
+  },
+  "beta": {
+    "_type": "quniform",
+    "_value": [1.0, 1.5, 0.1]
+  },
+  "gamma": {
+    "_type": "quniform",
+    "_value": [1.0, 1.5, 0.1]
+  }
+}

examples/trials/efficientnet/tuner.py

+from nni.gridsearch_tuner.gridsearch_tuner import GridSearchTuner
+
+
+class FixedProductTuner(GridSearchTuner):
+    """
+    This tuner is essentially grid search, but it guarantees all the parameters with alpha * beta^2 * gamma^2 is
+    approximately `product`.
+    """
+
+    def __init__(self, product):
+        """
+        :param product: the constant provided, should be 2 in EfficientNet-B1
+        """
+        super().__init__()
+        self.product = product
+
+    def expand_parameters(self, para):
+        """
+        Filter out all qualified parameters
+        """
+        para = super().expand_parameters(para)
+        if all([key in para[0] for key in ["alpha", "beta", "gamma"]]):  # if this is an interested set
+            ret_para = []
+            for p in para:
+                prod = p["alpha"] * (p["beta"] ** 2) * (p["gamma"] ** 2)
+                if abs(prod - self.product) < 0.1:
+                    ret_para.append(p)
+            return ret_para
+        return para