Skip to content
This repository has been archived by the owner on Sep 18, 2024. It is now read-only.

Commit

Permalink
Unified doc's name & update docs (#1069)
Browse files Browse the repository at this point in the history
* update docs
  • Loading branch information
PurityFan authored and QuanluZhang committed May 15, 2019
1 parent 0b864c7 commit bc0e55a
Show file tree
Hide file tree
Showing 60 changed files with 145 additions and 138 deletions.
46 changes: 23 additions & 23 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,32 +52,32 @@ The tool dispatches and runs trial jobs generated by tuning algorithms to search
</ul>
</td>
<td>
<a href="docs/en_US/Builtin_Tuner.md">Tuner</a>
<a href="docs/en_US/BuiltinTuner.md">Tuner</a>
<ul>
<li><a href="docs/en_US/Builtin_Tuner.md#TPE">TPE</a></li>
<li><a href="docs/en_US/Builtin_Tuner.md#Random">Random Search</a></li>
<li><a href="docs/en_US/Builtin_Tuner.md#Anneal">Anneal</a></li>
<li><a href="docs/en_US/Builtin_Tuner.md#Evolution">Naive Evolution</a></li>
<li><a href="docs/en_US/Builtin_Tuner.md#SMAC">SMAC</a></li>
<li><a href="docs/en_US/Builtin_Tuner.md#Batch">Batch</a></li>
<li><a href="docs/en_US/Builtin_Tuner.md#Grid">Grid Search</a></li>
<li><a href="docs/en_US/Builtin_Tuner.md#Hyperband">Hyperband</a></li>
<li><a href="docs/en_US/Builtin_Tuner.md#NetworkMorphism">Network Morphism</a></li>
<li><a href="docs/en_US/BuiltinTuner.md#TPE">TPE</a></li>
<li><a href="docs/en_US/BuiltinTuner.md#Random">Random Search</a></li>
<li><a href="docs/en_US/BuiltinTuner.md#Anneal">Anneal</a></li>
<li><a href="docs/en_US/BuiltinTuner.md#Evolution">Naive Evolution</a></li>
<li><a href="docs/en_US/BuiltinTuner.md#SMAC">SMAC</a></li>
<li><a href="docs/en_US/BuiltinTuner.md#Batch">Batch</a></li>
<li><a href="docs/en_US/BuiltinTuner.md#Grid">Grid Search</a></li>
<li><a href="docs/en_US/BuiltinTuner.md#Hyperband">Hyperband</a></li>
<li><a href="docs/en_US/BuiltinTuner.md#NetworkMorphism">Network Morphism</a></li>
<li><a href="examples/tuners/enas_nni/README.md">ENAS</a></li>
<li><a href="docs/en_US/Builtin_Tuner.md#NetworkMorphism#MetisTuner">Metis Tuner</a></li>
<li><a href="docs/en_US/Builtin_Tuner.md#BOHB">BOHB</a></li>
<li><a href="docs/en_US/BuiltinTuner.md#NetworkMorphism#MetisTuner">Metis Tuner</a></li>
<li><a href="docs/en_US/BuiltinTuner.md#BOHB">BOHB</a></li>
</ul>
<a href="docs/en_US/Builtin_Assessors.md#assessor">Assessor</a>
<a href="docs/en_US/BuiltinAssessors.md#assessor">Assessor</a>
<ul>
<li><a href="docs/en_US/Builtin_Assessors.md#Medianstop">Median Stop</a></li>
<li><a href="docs/en_US/Builtin_Assessors.md#Curvefitting">Curve Fitting</a></li>
<li><a href="docs/en_US/BuiltinAssessors.md#Medianstop">Median Stop</a></li>
<li><a href="docs/en_US/BuiltinAssessors.md#Curvefitting">Curve Fitting</a></li>
</ul>
</td>
<td>
<ul>
<li><a href="docs/en_US/LocalMode.md">Local Machine</a></li>
<li><a href="docs/en_US/RemoteMachineMode.md">Remote Servers</a></li>
<li><a href="docs/en_US/PAIMode.md">OpenPAI</a></li>
<li><a href="docs/en_US/PaiMode.md">OpenPAI</a></li>
<li><a href="docs/en_US/KubeflowMode.md">Kubeflow</a></li>
<li><a href="docs/en_US/FrameworkControllerMode.md">FrameworkController on K8S (AKS etc.)</a></li>
</ul>
Expand Down Expand Up @@ -229,24 +229,24 @@ You can use these commands to get more information about the experiment
## **How to**

* [Install NNI](docs/en_US/Installation.md)
* [Use command line tool nnictl](docs/en_US/NNICTLDOC.md)
* [Use command line tool nnictl](docs/en_US/Nnictl.md)
* [Use NNIBoard](docs/en_US/WebUI.md)
* [How to define search space](docs/en_US/SearchSpaceSpec.md)
* [How to define a trial](docs/en_US/Trials.md)
* [How to choose tuner/search-algorithm](docs/en_US/Builtin_Tuner.md)
* [How to choose tuner/search-algorithm](docs/en_US/BuiltinTuner.md)
* [Config an experiment](docs/en_US/ExperimentConfig.md)
* [How to use annotation](docs/en_US/Trials.md#nni-python-annotation)

## **Tutorials**

* [Run an experiment on local (with multiple GPUs)?](docs/en_US/LocalMode.md)
* [Run an experiment on multiple machines?](docs/en_US/RemoteMachineMode.md)
* [Run an experiment on OpenPAI?](docs/en_US/PAIMode.md)
* [Run an experiment on OpenPAI?](docs/en_US/PaiMode.md)
* [Run an experiment on Kubeflow?](docs/en_US/KubeflowMode.md)
* [Try different tuners](docs/en_US/tuners.rst)
* [Try different assessors](docs/en_US/assessors.rst)
* [Implement a customized tuner](docs/en_US/Customize_Tuner.md)
* [Implement a customized assessor](docs/en_US/Customize_Assessor.md)
* [Implement a customized tuner](docs/en_US/CustomizeTuner.md)
* [Implement a customized assessor](docs/en_US/CustomizeAssessor.md)
* [Use Genetic Algorithm to find good model architectures for Reading Comprehension task](examples/trials/ga_squad/README.md)

## **Contribute**
Expand All @@ -255,9 +255,9 @@ This project welcomes contributions and suggestions, we use [GitHub issues](http

Issues with the **good first issue** label are simple and easy-to-start ones that we recommend new contributors to start with.

To set up environment for NNI development, refer to the instruction: [Set up NNI developer environment](docs/en_US/SetupNNIDeveloperEnvironment.md)
To set up environment for NNI development, refer to the instruction: [Set up NNI developer environment](docs/en_US/SetupNniDeveloperEnvironment.md)

Before start coding, review and get familiar with the NNI Code Contribution Guideline: [Contributing](docs/en_US/CONTRIBUTING.md)
Before start coding, review and get familiar with the NNI Code Contribution Guideline: [Contributing](docs/en_US/Contributing.md)

We are in construction of the instruction for [How to Debug](docs/en_US/HowToDebug.md), you are also welcome to contribute questions or suggestions on this area.

Expand Down
2 changes: 1 addition & 1 deletion docs/en_US/AdvancedNAS.md → docs/en_US/AdvancedNas.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ With the NFS setup (see below), trial code can share model weight through loadin
```yaml
tuner:
codeDir: path/to/customer_tuner
classFileName: customer_tuner.py
classFileName: customer_tuner.py
className: CustomerTuner
classArgs:
...
Expand Down
5 changes: 3 additions & 2 deletions docs/en_US/AnnotationSpec.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,15 @@
# NNI Annotation
# NNI Annotation

## Overview

To improve user experience and reduce user effort, we design an annotation grammar. Using NNI annotation, users can adapt their code to NNI just by adding some standalone annotating strings, which does not affect the execution of the original code.
To improve user experience and reduce user effort, we design an annotation grammar. Using NNI annotation, users can adapt their code to NNI just by adding some standalone annotating strings, which does not affect the execution of the original code.

Below is an example:

```python
'''@nni.variable(nni.choice(0.1, 0.01, 0.001), name=learning_rate)'''
learning_rate = 0.1

```
The meaning of this example is that NNI will choose one of several values (0.1, 0.01, 0.001) to assign to the learning_rate variable. Specifically, this first line is an NNI annotation, which is a single string. Following is an assignment statement. What nni does here is to replace the right value of this assignment statement according to the information provided by the annotation line.

Expand Down
File renamed without changes.
File renamed without changes.
File renamed without changes.
4 changes: 2 additions & 2 deletions docs/en_US/Blog/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -5,5 +5,5 @@ Research Blog
.. toctree::
:maxdepth: 2

Hyperparameter Optimization Comparison<HPOComparison>
Neural Architecture Search Comparison<NASComparison>
Hyperparameter Optimization Comparison<HpoComparison>
Neural Architecture Search Comparison<NasComparison>
2 changes: 1 addition & 1 deletion docs/en_US/bohbAdvisor.md → docs/en_US/BohbAdvisor.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Below we divide introduction of the BOHB process into two parts:

### HB (Hyperband)

We follow Hyperband’s way of choosing the budgets and continue to use SuccessiveHalving, for more details, you can refer to the [Hyperband in NNI](hyperbandAdvisor.md) and [reference paper of Hyperband](https://arxiv.org/abs/1603.06560). This procedure is summarized by the pseudocode below.
We follow Hyperband’s way of choosing the budgets and continue to use SuccessiveHalving, for more details, you can refer to the [Hyperband in NNI](HyperbandAdvisor.md) and [reference paper of Hyperband](https://arxiv.org/abs/1603.06560). This procedure is summarized by the pseudocode below.

![](../img/bohb_1.png)

Expand Down
File renamed without changes.
File renamed without changes.
File renamed without changes.
4 changes: 2 additions & 2 deletions docs/en_US/CONTRIBUTING.md → docs/en_US/Contributing.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ When raising issues, please specify the following:

Provide PRs with appropriate tags for bug fixes or enhancements to the source code. Do follow the correct naming conventions and code styles when you work on and do try to implement all code reviews along the way.

If you are looking for How to develop and debug the NNI source code, you can refer to [How to set up NNI developer environment doc](./SetupNNIDeveloperEnvironment.md) file in the `docs` folder.
If you are looking for How to develop and debug the NNI source code, you can refer to [How to set up NNI developer environment doc](./SetupNniDeveloperEnvironment.md) file in the `docs` folder.

Similarly for [Quick Start](QuickStart.md). For everything else, refer to [NNI Home page](http://nni.readthedocs.io).

Expand All @@ -39,7 +39,7 @@ A person looking to contribute can take up an issue by claiming it as a comment/

## Code Styles & Naming Conventions
* We follow [PEP8](https://www.python.org/dev/peps/pep-0008/) for Python code and naming conventions, do try to adhere to the same when making a pull request or making a change. One can also take the help of linters such as `flake8` or `pylint`
* We also follow [NumPy Docstring Style](https://www.sphinx-doc.org/en/master/usage/extensions/example_numpy.html#example-numpy) for Python Docstring Conventions. During the [documentation building](CONTRIBUTING.md#documentation), we use [sphinx.ext.napoleon](https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html) to generate Python API documentation from Docstring.
* We also follow [NumPy Docstring Style](https://www.sphinx-doc.org/en/master/usage/extensions/example_numpy.html#example-numpy) for Python Docstring Conventions. During the [documentation building](Contributing.md#documentation), we use [sphinx.ext.napoleon](https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html) to generate Python API documentation from Docstring.

## Documentation
Our documentation is built with [sphinx](http://sphinx-doc.org/), supporting [Markdown](https://guides.github.com/features/mastering-markdown/) and [reStructuredText](http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) format. All our documentations are placed under [docs/en_US](https://github.com/Microsoft/nni/tree/master/docs).
Expand Down
File renamed without changes.
File renamed without changes.
File renamed without changes.
Original file line number Diff line number Diff line change
Expand Up @@ -109,4 +109,4 @@ More detail example you could see:
### Write a more advanced automl algorithm

The methods above are usually enough to write a general tuner. However, users may also want more methods, for example, intermediate results, trials' state (e.g., the methods in assessor), in order to have a more powerful automl algorithm. Therefore, we have another concept called `advisor` which directly inherits from `MsgDispatcherBase` in [`src/sdk/pynni/nni/msg_dispatcher_base.py`](https://github.com/Microsoft/nni/tree/master/src/sdk/pynni/nni/msg_dispatcher_base.py). Please refer to [here](Customize_Advisor.md) for how to write a customized advisor.
The methods above are usually enough to write a general tuner. However, users may also want more methods, for example, intermediate results, trials' state (e.g., the methods in assessor), in order to have a more powerful automl algorithm. Therefore, we have another concept called `advisor` which directly inherits from `MsgDispatcherBase` in [`src/sdk/pynni/nni/msg_dispatcher_base.py`](https://github.com/Microsoft/nni/tree/master/src/sdk/pynni/nni/msg_dispatcher_base.py). Please refer to [here](CustomizeAdvisor.md) for how to write a customized advisor.
File renamed without changes.
12 changes: 0 additions & 12 deletions docs/en_US/Examples.rst

This file was deleted.

2 changes: 1 addition & 1 deletion docs/en_US/ExperimentConfig.md
Original file line number Diff line number Diff line change
Expand Up @@ -169,7 +169,7 @@ machineList:
* __remote__ submit trial jobs to remote ubuntu machines, and __machineList__ field should be filed in order to set up SSH connection to remote machine.
* __pai__ submit trial jobs to [OpenPai](https://github.com/Microsoft/pai) of Microsoft. For more details of pai configuration, please reference [PAIMOdeDoc](./PAIMode.md)
* __pai__ submit trial jobs to [OpenPai](https://github.com/Microsoft/pai) of Microsoft. For more details of pai configuration, please reference [PAIMOdeDoc](./PaiMode.md)
* __kubeflow__ submit trial jobs to [kubeflow](https://www.kubeflow.org/docs/about/kubeflow/), NNI support kubeflow based on normal kubernetes and [azure kubernetes](https://azure.microsoft.com/en-us/services/kubernetes-service/).
Expand Down
16 changes: 11 additions & 5 deletions docs/en_US/FAQ.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,13 @@

This page is for frequent asked questions and answers.


### tmp folder fulled
nnictl will use tmp folder as a temporary folder to copy files under codeDir when executing experimentation creation.
nnictl will use tmp folder as a temporary folder to copy files under codeDir when executing experimentation creation.
When met errors like below, try to clean up **tmp** folder first.
> OSError: [Errno 28] No space left on device
### Cannot get trials' metrics in OpenPAI mode
In OpenPAI training mode, we start a rest server which listens on 51189 port in NNI Manager to receive metrcis reported from trials running in OpenPAI cluster. If you didn't see any metrics from WebUI in OpenPAI mode, check your machine where NNI manager runs on to make sure 51189 port is turned on in the firewall rule.
In OpenPAI training mode, we start a rest server which listens on 51189 port in NNI Manager to receive metrcis reported from trials running in OpenPAI cluster. If you didn't see any metrics from WebUI in OpenPAI mode, check your machine where NNI manager runs on to make sure 51189 port is turned on in the firewall rule.

### Segmentation Fault (core dumped) when installing
> make: *** [install-XXX] Segmentation fault (core dumped)
Expand All @@ -19,7 +18,7 @@ Please try the following solutions in turn:
* Install NNI with `--no-cache-dir` flag like `python3 -m pip install nni --no-cache-dir`

### Job management error: getIPV4Address() failed because os.networkInterfaces().eth0 is undefined.
Your machine don't have eth0 device, please set [nniManagerIp](ExperimentConfig.md) in your config file manually.
Your machine don't have eth0 device, please set [nniManagerIp](ExperimentConfig.md) in your config file manually.

### Exceed the MaxDuration but didn't stop
When the duration of experiment reaches the maximum duration, nniManager will not create new trials, but the existing trials will continue unless user manually stop the experiment.
Expand All @@ -28,7 +27,14 @@ When the duration of experiment reaches the maximum duration, nniManager will no
If you upgrade your NNI or you delete some config files of NNI when there is an experiment running, this kind of issue may happen because the loss of config file. You could use `ps -ef | grep node` to find the pid of your experiment, and use `kill -9 {pid}` to kill it manually.

### Could not get `default metric` in webUI of virtual machines
Config the network mode to bridge mode or other mode that could make virtual machine's host accessible from external machine, and make sure the port of virtual machine is not forbidden by firewall.
Config the network mode to bridge mode or other mode that could make virtual machine's host accessible from external machine, and make sure the port of virtual machine is not forbidden by firewall.

### Could not open webUI link
Unable to open the WebUI may have the following reasons:

* http://127.0.0.1, http://172.17.0.1 and http://10.0.0.15 are referred to localhost, if you start your experiment on the server or remote machine. You can replace the IP to your server IP to view the WebUI, like http://[your_server_ip]:8080
* If you still can't see the WebUI after you use the server IP, you can check the proxy and the firewall of your machine. Or use the browser on the machine where you start your NNI experiment.
* Another reason may be your experiment is failed and NNI may fail to get the experiment infomation. You can check the log of NNImanager in the following directory: ~/nni/experiment/[your_experiment_id] /log/nnimanager.log

### Windows local mode problems
Please refer to [NNI Windows local mode](WindowsLocalMode.md)
Expand Down
2 changes: 1 addition & 1 deletion docs/en_US/FrameworkControllerMode.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,4 +100,4 @@ Trial configuration in frameworkcontroller mode have the following configuration
After you prepare a config file, you could run your experiment by nnictl. The way to start an experiment on frameworkcontroller is similar to kubeflow, please refer the [document](./KubeflowMode.md) for more information.
## version check
NNI support version check feature in since version 0.6, [refer](PAIMode.md)
NNI support version check feature in since version 0.6, [refer](PaiMode.md)
File renamed without changes.
File renamed without changes.
2 changes: 1 addition & 1 deletion docs/en_US/HowToDebug.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ There are three kinds of log in NNI. When creating a new experiment, you can spe

All possible errors that happen when launching an NNI experiment can be found here.

You can use `nnictl log stderr` to find error information. For more options please refer to [NNICTL](NNICTLDOC.md)
You can use `nnictl log stderr` to find error information. For more options please refer to [NNICTL](Nnictl.md)


### Experiment Root Directory
Expand Down
4 changes: 2 additions & 2 deletions docs/en_US/HowToImplementTrainingService.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ TrainingService is a module related to platform management and job schedule in N
## System architecture
![](../img/NNIDesign.jpg)

The brief system architecture of NNI is shown in the picture. NNIManager is the core management module of system, in charge of calling TrainingService to manage trial jobs and the communication between different modules. Dispatcher is a message processing center responsible for message dispatch. TrainingService is a module to manage trial jobs, it communicates with nniManager module, and has different instance according to different training platform. For the time being, NNI supports local platfrom, [remote platfrom](RemoteMachineMode.md), [PAI platfrom](PAIMode.md), [kubeflow platform](KubeflowMode.md) and [FrameworkController platfrom](FrameworkController.md).
The brief system architecture of NNI is shown in the picture. NNIManager is the core management module of system, in charge of calling TrainingService to manage trial jobs and the communication between different modules. Dispatcher is a message processing center responsible for message dispatch. TrainingService is a module to manage trial jobs, it communicates with nniManager module, and has different instance according to different training platform. For the time being, NNI supports local platfrom, [remote platfrom](RemoteMachineMode.md), [PAI platfrom](PaiMode.md), [kubeflow platform](KubeflowMode.md) and [FrameworkController platfrom](FrameworkController.md).
In this document, we introduce the brief design of TrainingService. If users want to add a new TrainingService instance, they just need to complete a child class to implement TrainingService, don't need to understand the code detail of NNIManager, Dispatcher or other modules.

## Folder structure of code
Expand Down Expand Up @@ -146,4 +146,4 @@ When users submit a trial job to cloud platform, they should wrap their trial co
## Reference

For more information about how to debug, please [refer](HowToDebug.md).
The guide line of how to contribute, please [refer](CONTRIBUTING).
The guide line of how to contribute, please [refer](Contributing.md).
File renamed without changes.
File renamed without changes.
Loading

0 comments on commit bc0e55a

Please sign in to comment.