Search Space Zoo nas bench 201

docs/en_US/NAS/Overview.md

@@ -64,6 +64,7 @@ Search Space Zoo contains the following NAS cells:
 * [DartsCell](./SearchSpaceZoo.md#DartsCell)
 * [ENAS micro](./SearchSpaceZoo.md#ENASMicroLayer)
 * [ENAS macro](./SearchSpaceZoo.md#ENASMacroLayer)
+* [NAS Bench 201](./SearchSpaceZoo.md#nas-bench-201)
 
 ## Using NNI API to Write Your Search Space
 

docs/en_US/NAS/SearchSpaceZoo.md

@@ -2,13 +2,13 @@
 
 ## DartsCell
 
-DartsCell is extracted from [CNN model](./DARTS.md) designed [here](https://github.com/microsoft/nni/tree/master/examples/nas/darts). A DartsCell is a directed acyclic graph containing an ordered sequence of N nodes and each node stands for a latent representation (e.g. feature map in a convolutional network). Directed edges from Node 1 to Node 2 are associated with some operations that transform Node 1 and the result is stored on Node 2. The [operations](#darts-predefined-operations) between nodes is predefined and unchangeable. One edge represents an operation that chosen from the predefined ones to be applied to the starting node of the edge. One cell contains two input nodes, a single output node, and other `n_node` nodes. The input nodes are defined as the cell outputs in the previous two layers. The output of the cell is obtained by applying a reduction operation (e.g. concatenation) to all the intermediate nodes. To make the search space continuous, the categorical choice of a particular operation is relaxed to a softmax over all possible operations. By adjusting the weight of softmax on every node, the operation with the highest probability is chosen to be part of the final structure. A CNN model can be formed by stacking several cells together, which builds a search space. Note that, in DARTS paper all cells in the model share the same structure.
+DartsCell is extracted from [CNN model](./DARTS.md) designed [here](https://github.com/microsoft/nni/tree/master/examples/nas/darts). A DartsCell is a directed acyclic graph containing an ordered sequence of N nodes and each node stands for a latent representation (e.g. feature map in a convolutional network). Directed edges from Node 1 to Node 2 are associated with some operations that transform Node 1 and the result is stored on Node 2. The [Candidate operators](#predefined-operations-darts) between nodes is predefined and unchangeable. One edge represents an operation that chosen from the predefined ones to be applied to the starting node of the edge. One cell contains two input nodes, a single output node, and other `n_node` nodes. The input nodes are defined as the cell outputs in the previous two layers. The output of the cell is obtained by applying a reduction operation (e.g. concatenation) to all the intermediate nodes. To make the search space continuous, the categorical choice of a particular operation is relaxed to a softmax over all possible operations. By adjusting the weight of softmax on every node, the operation with the highest probability is chosen to be part of the final structure. A CNN model can be formed by stacking several cells together, which builds a search space. Note that, in DARTS paper all cells in the model share the same structure.
 
 One structure in the Darts search space is shown below. Note that, NNI merges the last one of the four intermediate nodes and the output node.
 
 ![](../../img/NAS_Darts_cell.svg)
 
-The predefined operations are shown in [references](#predefined-operations-darts).
+The predefined operators are shown [here](#predefined-operations-darts).
 
 ```eval_rst
 ..  autoclass:: nni.nas.pytorch.search_space_zoo.DartsCell
@@ -28,9 +28,9 @@ python3 darts_example.py
 
 <a name="predefined-operations-darts"></a>
 
-### References
+### Candidate operators
 
-All supported operations for Darts are listed below.
+All supported operators for Darts are listed below.
 
 * MaxPool / AvgPool
   * MaxPool: Call `torch.nn.MaxPool2d`. This operation applies a 2D max pooling over all input channels. Its parameters `kernel_size=3` and `padding=1` are fixed. The pooling result will pass through a BatchNorm2d then return as the result.
@@ -65,11 +65,11 @@ This layer is extracted from the model designed [here](https://github.com/micros
 
 ENAS Micro employs a DAG with N nodes in one cell, where the nodes represent local computations, and the edges represent the flow of information between the N nodes. One cell contains two input nodes and a single output node. The following nodes choose two previous nodes as input and apply two operations from [predefined ones](#predefined-operations-enas) then add them as the output of this node. For example, Node 4 chooses Node 1 and Node 3 as inputs then applies `MaxPool` and `AvgPool` on the inputs respectively, then adds and sums them as the output of Node 4. Nodes that are not served as input for any other node are viewed as the output of the layer. If there are multiple output nodes, the model will calculate the average of these nodes as the layer output.
 
-One structure in the ENAS micro search space is shown below.
+The ENAS micro search space is shown below.
 
 ![](../../img/NAS_ENAS_micro.svg) 
 
-The predefined operations can be seen [here](#predefined-operations-enas).
+The predefined operators can be seen [here](#predefined-operations-enas).
 
 ```eval_rst
 ..  autoclass:: nni.nas.pytorch.search_space_zoo.ENASMicroLayer
@@ -91,9 +91,9 @@ python3 enas_micro_example.py
 
 <a name="predefined-operations-enas"></a>
 
-### References
+### Candidate operators
 
-All supported operations for ENAS micro search are listed below.
+All supported operators for ENAS micro search are listed below.
 
 * MaxPool / AvgPool
     * MaxPool: Call `torch.nn.MaxPool2d`. This operation applies a 2D max pooling over all input channels followed by BatchNorm2d. Its parameters are fixed to `kernel_size=3`, `stride=1` and `padding=1`.
@@ -116,7 +116,7 @@ All supported operations for ENAS micro search are listed below.
 
 ## ENASMacroLayer
 
-In Macro search, the controller makes two decisions for each layer: i) the [operation](#macro-operations) to perform on the result of the previous layer, ii) which the previous layer to connect to for SkipConnects. ENAS uses a controller to design the whole model architecture instead of one of its components. The output of operations is going to concat with the tensor of the chosen layer for SkipConnect. NNI provides [predefined operations](#macro-operations) for macro search, which are listed in [references](#macro-operations).
+In Macro search, the controller makes two decisions for each layer: i) the [operation](#macro-operations) to perform on the result of the previous layer, ii) which the previous layer to connect to for SkipConnects. ENAS uses a controller to design the whole model architecture instead of one of its components. The output of operations is going to concat with the tensor of the chosen layer for SkipConnect. NNI provides [predefined operators](#macro-operations) for macro search, which are listed in [Candidate operators](#macro-operations).
 
 Part of one structure in the ENAS macro search space is shown below.
 
@@ -147,9 +147,9 @@ python3 enas_macro_example.py
 
 <a name="macro-operations"></a>
 
-### References
+### Candidate operators
 
-All supported operations for ENAS macro search are listed below.
+All supported operators for ENAS macro search are listed below.
 
 * ConvBranch
 
@@ -172,4 +172,65 @@ All supported operations for ENAS macro search are listed below.
     ..  autoclass:: nni.nas.pytorch.search_space_zoo.enas_ops.PoolBranch
     ```
 
-<!-- push -->
+## NAS-Bench-201
+
+NAS Bench 201 defines a unified search space, which is algorithm agnostic. The predefined skeleton consists of a stack of cells that share the same architecture. Every cell contains four nodes and a DAG is formed by connecting edges among them, where the node represents the sum of feature maps and the edge stands for an operation transforming a tensor from the source node to the target node. The predefined candidate operators can be found in [Candidate operators](#nas-bench-201-reference).
+
+The search space of NAS Bench 201 is shown below.
+
+![](../../img/NAS_Bench_201.svg)
+
+```eval_rst
+..  autoclass:: nni.nas.pytorch.nasbench201.NASBench201Cell
+    :members:
+```
+
+### Example code
+
+[example code](https://github.com/microsoft/nni/tree/master/examples/nas/search_space_zoo/nas_bench_201.py)
+
+```bash
+# for structure searching
+git clone https://github.com/Microsoft/nni.git
+cd nni/examples/nas/search_space_zoo
+python3 nas_bench_201.py
+```
+
+<a name="nas-bench-201-reference"></a>
+
+### Candidate operators
+
+All supported operators for NAS Bench 201 are listed below.
+
+* AvgPool
+
+  If the number of input channels is not equal to the number of output channels, the input will first pass through a `ReLUConvBN` layer with `kernel_size=1`, `stride=1`, `padding=0`, and `dilation=0`.
+  Call `torch.nn.AvgPool2d`. This operation applies a 2D average pooling over all input channels followed by BatchNorm2d. Its parameters are fixed to `kernel_size=3` and `padding=1`.
+
+  ```eval_rst
+  ..  autoclass:: nni.nas.pytorch.nasbench201.nasbench201_ops.Pooling
+      :members:
+  ```
+
+* Conv
+  * Conv1x1: Consist of a sequence of ReLU, `nn.Cinv2d` and BatchNorm. The Conv operation's parameter is fixed to `kernal_size=1`, `padding=0`, and `dilation=1`.
+  * Conv3x3: Consist of a sequence of ReLU, `nn.Cinv2d` and BatchNorm. The Conv operation's parameter is fixed to `kernal_size=3`, `padding=1`, and `dilation=1`.
+
+  ```eval_rst
+  ..  autoclass:: nni.nas.pytorch.nasbench201.nasbench201_ops.ReLUConvBN
+      :members:
+  ```
+
+* SkipConnect
+
+  Call `torch.nn.Identity` to connect directly to the next cell.
+
+* Zeroize
+
+  Generate zero tensors indicating there is no connection from the source node to the target node.
+
+  ```eval_rst
+  ..  autoclass:: nni.nas.pytorch.nasbench201.nasbench201_ops.Zero
+      :members:
+  ```
+