Maxpool spec update

docs/ops/pooling/MaxPool_1.md

@@ -4,9 +4,9 @@
 
 **Category**: *Pooling*
 
-**Short description**: [Reference](http://caffe.berkeleyvision.org/tutorial/layers/pooling.html)
+**Short description**: Performs max pooling operation on input.
 
-**Detailed description**: [Reference](http://cs231n.github.io/convolutional-networks/#pool)
+**Detailed description**: Input shape can be either 3D, 4D or 5D. Max Pooling operation is performed with the respect to input shape from the third dimension to the last dimension. If paddings are used then during the pooling calculation their value is `-inf`. [Article about max pooling in Convolutional Networks](https://deeplizard.com/learn/video/ZjM_XQa5s6s). 
 
 **Attributes**: *Pooling* attributes are specified in the `data` node, which is a child of the layer node.
 
@@ -46,7 +46,7 @@
 
 * *rounding_type*
 
-  * **Description**: *rounding_type* is a type of rounding to be applied.
+  * **Description**: *rounding_type* is a type of rounding to be used to compute output shape.
   * **Range of values**:
     * *ceil*
     * *floor*
@@ -63,24 +63,188 @@
   * **Type**: string
   * **Default value**: *explicit*
   * **Required**: *no*
-  * **Note**: *pads_begin* and *pads_end* attributes are ignored when *auto_pad* is specified.
+  * **Note**: *pads_begin* and *pads_end* attributes are ignored when *auto_pad* is not equal to explicit.
 
 **Inputs**:
 
-*   **1**: 4D or 5D input tensor. Required.
+*   **1**: 3D, 4D or 5D input tensor. Required.
+
+**Outputs**:
+  * **1**: Input shape can be either [N,C,H], [N,C,H,W] or [N,C,H,W,D]. Then the corresponding output shape will be [N,C,H_out], [N,C,H_out,W_out] or [N,C,H_out,W_out,D_out]
 
 **Mathematical Formulation**
+Output shape calculation based on `auto_pad` and `rounding_type`:  
+  * `auto_pad = explicit` and `rounding_type = floor`   
+          `H_out = floor(H + pads_begin[0] + pads_end[0] - kernel[0] / strides[0]) + 1`  
+          `W_out = floor(W + pads_begin[1] + pads_end[1] - kernel[1] / strides[1]) + 1`  
+          `D_out = floor(D + pads_begin[2] + pads_end[2] - kernel[2] / strides[2]) + 1`   
+
+  * `auto_pad = valid` and `rounding_type = floor`  
+        `H_out = floor(H - kernel[0] / strides[0]) + 1`   
+        `W_out = floor(W - kernel[1] / strides[1]) + 1`    
+        `D_out = floor(D - kernel[2] / strides[2]) + 1`  
+
+  * `auto_pad = same_upper/same_lower` and `rounding_type = floor`  
+        `H_out = H`   
+        `W_out = W`    
+        `D_out = D`  
+
+  * `auto_pad = explicit` and `rounding_type = ceil`  
+        `H_out = ceil(H + pads_begin[0] + pads_end[0] - kernel[0] / strides[0]) + 1`   
+        `W_out = ceil(W + pads_begin[1] + pads_end[1] - kernel[1] / strides[1]) + 1`    
+        `D_out = ceil(D + pads_begin[2] + pads_end[2] - kernel[2] / strides[2]) + 1`    
+
+  * `auto_pad = valid` and `rounding_type = ceil`  
+        `H_out = ceil(H - kernel[0] / strides[0]) + 1`   
+        `W_out = ceil(W - kernel[1] / strides[1]) + 1`    
+        `D_out = ceil(D - kernel[2] / strides[2]) + 1`  
+
+  * `auto_pad = same_upper/same_lower` and `rounding_type = ceil`  
+        `H_out = H`   
+        `W_out = W`    
+        `D_out = D`  
+
+If `H + pads_begin[i] + pads_end[i] - kernel[i]` is not divided by `strides[i]` evenly then the result is rounded with the respect to `rounding_type` attribute. 
+
+Example 1 shows how *MaxPool* operates with 4D input using 2D kernel and `auto_pad = explicit`
+
+```
+input = [[[[-1, 2, 3],
+           [4, 5, -6],
+           [-7, 8, 9]]]]
+strides = [1, 1]
+pads_begin = [1, 1]
+pads_end = [1, 1]
+kernel = [2, 2]
+rounding_type = "floor"
+auto_pad = "explicit"
+output = [[[[-1, 2, 3, 3],
+            [4, 5, 5, -6],
+            [4, 8, 9, 9],
+            [-7, 8, 9, 9]]]]
+```
+
+Example 2 shows how *MaxPool* operates with 3D input using 1D kernel and `auto_pad = valid`
+
+```
+input = [[[-1, 2, 3, 5, -7, 9, 1]]]
+strides = [1]
+kernel = [3]
+rounding_type = "floor"
+auto_pad = "valid"
+output = [[[3, 5, 5, 9, 9]]]
+```
+
+Example 3 shows how *MaxPool* operates with 4D input using 2D kernel and `auto_pad = same_lower`
+
+```
+input = [[[[-1, 2, 3],
+         [4, 5, -6],
+         [-7, 8, 9]]]]
+strides = [1, 1]
+kernel = [2, 2]
+rounding_type = "floor"
+auto_pad = "same_lower"
+output = [[[[-1, 2, 3],
+            [4, 5, 5]
+            [4, 8, 9]]]]
+```
+
+Example 4 shows how *MaxPool* operates with 4D input using 2D kernel and `auto_pad = same_upper`
+
+```
+input = [[[[-1, 2, 3],
+           [4, 5, -6],
+           [-7, 8, 9]],
+          [[2, -1, 5],
+           [6, -7, 1],
+           [8, 2, -3]]]]
+strides = [1, 1]
+kernel = [2, 2]
+rounding_type = "floor"
+auto_pad = "same_upper"
+output = [[[[5, 5, -6],
+            [8, 9, 9]
+            [8, 9, 9]],
+           [[6, 5, 5],
+            [8, 2, 1],
+            [8, 2, -3]]]]
+```
+
+Example 5 shows how *MaxPool* operates with 4D input using 2D kernel, `auto_pad = valid` and `rounding_type = ceil`
+
+```
+input = [[[[-1, 2, 3],
+           [4, 5, -6],
+           [-7, 8, 9]]]]
+strides = [2, 2]
+kernel = [2, 2]
+rounding_type = "ceil"
+auto_pad = "valid"
+output = [[[[5, 3],
+            [8, 9]]]]
+```
+
+**Examples**
 
-    \f[
-    output_{j} = max(x_{0}, ..., x_{i})
-    \f]
+```xml
+<layer ... type="MaxPool" ... >
+        <data auto_pad="same_upper" kernel="2,2" strides="2,2"/>
+        <input> 
+          <port id="0">
+            <dim>1</dim>
+            <dim>3</dim>
+            <dim>32</dim>
+            <dim>32</dim>
+          </port>
+        </input>
+        <output>
+          <port id="1">
+            <dim>1</dim>
+            <dim>3</dim>
+            <dim>32</dim>
+            <dim>32</dim>
+          </port>
+    </output>
+</layer>
 
-**Example**
+<layer ... type="MaxPool" ... >
+        <data auto_pad="explicit" kernel="2,2" pads_begin="1,1" pads_end="1,1" strides="2,2"/>
+        <input> 
+          <port id="0">
+            <dim>1</dim>
+            <dim>3</dim>
+            <dim>32</dim>
+            <dim>32</dim>
+          </port>
+        </input>
+        <output>
+          <port id="1">
+            <dim>1</dim>
+            <dim>3</dim>
+            <dim>17</dim>
+            <dim>17</dim>
+          </port>
+    </output>
+</layer>
 
-```xml
 <layer ... type="MaxPool" ... >
-        <data auto_pad="same_upper" kernel="3,3" pads_begin="0,0" pads_end="1,1" strides="2,2"/>
-        <input> ... </input>
-        <output> ... </output>
+        <data auto_pad="valid" kernel="2,2" strides="2,2"/>
+        <input> 
+          <port id="0">
+            <dim>1</dim>
+            <dim>3</dim>
+            <dim>32</dim>
+            <dim>32</dim>
+          </port>
+        </input>
+        <output>
+          <port id="1">
+            <dim>1</dim>
+            <dim>3</dim>
+            <dim>16</dim>
+            <dim>16</dim>
+          </port>
+    </output>
 </layer>
 ```