Merge pull request #121 from Microsoft/master

merge master

zh_CN/test/naive_test/README.md

+## 用法
+
+* 安装前测试： `python3 run.py --preinstall`
+* 安装的集成测试： `python3 run.py`
+* 如果没有问题，最终会打印绿色的 `PASS`。
+
+## 详细说明
+
+* 这是测试 Trial 和 Tuner、Assessor 之间通信的测试用例。
+* Trial 会收到整数 `x` 作为参数，并返回 `x`, `x²`, `x³`, ... , `x¹⁰` 作为指标。
+* Tuner 会简单的生成自然数序列，并将收到的指标输出到 `tuner_result.txt`。
+* 当 `sum(metrics) % 11 == 1` 时，Assessor 会终止 Trial，并将终止的 Trial 输出到 `assessor_result.txt`。
+* 当 Tuner 和 Assessor 发生异常时，会在相应的文件中输出 `ERROR`。
+* 当 Experiment 结束时，也表示用例成功执行，可以在 nni_manager.log 文件中找到 `Experiment done`。
+
+## 问题
+
+* 使用了私有 API 来检测是否 Tuner 和 Assessor 成功结束。 
+* RESTful 服务的输出未测试。
+* 远程计算机训练服务没有测试。
\ No newline at end of file

zh_CN/tools/README.md

+## NNI CTL
+
+NNI CTL 模块用来控制 Neural Network Intelligence，包括开始新 Experiment，停止 Experiment，更新 Experiment等。
+
+## 环境
+
+    Ubuntu 16.04 或其它 Linux 操作系统。
+    python >= 3.5
+    
+
+## 安装
+
+1. 进入 tools 目录
+
+2. 使用 pip 来安装包
+    
+    - 为当前用户安装：
+        
+        ```bash
+        python3 -m pip install --user -e .
+        ```
+    
+    - 为所有用户安装:
+        
+        ```bash
+        python3 -m pip install -e .
+        ```
+
+3. 修改 nnictl 文件的权限
+    
+    ```bash
+    chmod +x ./nnictl
+    ```
+
+4. 将 nnictl 添加到系统的 PATH 环境变量中。
+    
+    - 可以用 `export` 命令来临时设置 PATH 变量。
+        
+        export PATH={your nnictl path}:$PATH
+    
+    - 或者编辑 `/etc/profile` 文件。
+        
+        ```txt
+        1.sudo vim /etc/profile
+        
+        2.在文件末尾加上
+        
+            export PATH={your nnictl path}:$PATH
+        
+        保存并退出。
+        
+        3.source /etc/profile
+        ```
+
+## 开始使用 NNI CTL
+
+参考 [NNI CTL 文档](../docs/NNICTLDOC.md)。
\ No newline at end of file

zh_CN/tools/nni_annotation/README.md

+# NNI Annotation 介绍
+
+为了获得良好的用户体验并减少用户负担，NNI 设计了通过注释来使用的语法。
+
+使用 NNI 时，只需要:
+
+1. 在超参变量前加上如下标记：
+    
+    '''@nni.variable(nni.choice(2,3,5,7),name=self.conv_size)'''
+
+2. 在中间结果前加上：
+    
+    '''@nni.report_intermediate_result(test_acc)'''
+
+3. 在输出结果前加上：
+    
+    '''@nni.report_final_result(test_acc)'''
+
+4. 在代码中使用函数 `function_choice`：
+    
+    '''@nni.function_choice(max_pool(h_conv1, self.pool_size),avg_pool(h_conv1, self.pool_size),name=max_pool)'''
+
+通过这种方法，能够轻松的在 NNI 中实现自动调参。
+
+`@nni.variable`, `nni.choice` 为搜索空间的类型，通过以下 10 种方法来定义搜索空间：
+
+1. `@nni.variable(nni.choice(option1,option2,...,optionN),name=variable)`  
+    变量值是选项中的一种，这些变量可以是任意的表达式。
+
+2. `@nni.variable(nni.randint(upper),name=variable)`  
+    变量可以是范围 [0, upper) 中的任意整数。
+
+3. `@nni.variable(nni.uniform(low, high),name=variable)`  
+    变量值会是 low 和 high 之间均匀分布的某个值。
+
+4. `@nni.variable(nni.quniform(low, high, q),name=variable)`  
+    变量值会是 low 和 high 之间均匀分布的某个值，公式为：round(uniform(low, high) / q) * q
+
+5. `@nni.variable(nni.loguniform(low, high),name=variable)`  
+    变量值是 exp(uniform(low, high)) 的点，数值以对数均匀分布。
+
+6. `@nni.variable(nni.qloguniform(low, high, q),name=variable)`  
+    变量值会是 low 和 high 之间均匀分布的某个值，公式为：round(exp(uniform(low, high)) / q) * q
+
+7. `@nni.variable(nni.normal(label, mu, sigma),name=variable)`  
+    变量值为正态分布的实数值，平均值为 mu，标准方差为 sigma。
+
+8. `@nni.variable(nni.qnormal(label, mu, sigma, q),name=variable)`  
+    变量值分布的公式为： round(normal(mu, sigma) / q) * q
+
+9. `@nni.variable(nni.lognormal(label, mu, sigma),name=variable)`  
+    变量值分布的公式为： exp(normal(mu, sigma))
+
+10. `@nni.variable(nni.qlognormal(label, mu, sigma, q),name=variable)`  
+    变量值分布的公式为： round(exp(normal(mu, sigma)) / q) * q
\ No newline at end of file