Quantize and Dequantize documentation (#1830)

* add stub files for quant dequant

* quantize / dequantize doc

* Small doxygen fixes

* Update quantize.rst

* quant docs

doc/sphinx/source/ops/dequantize.rst

+.. dequantize.rst: 
+
+##########
+Dequantize
+##########
+
+.. code-block:: cpp
+
+   Dequantize // Maps quantized input to real output
+
+Description
+===========
+
+Produces a tensor of element type ``type`` and the same shape as ``input``
+where the value of each coordinate :math:`i` of ``output`` is the corresponding coordinate of 
+``input`` plus ``offset`` quantity multiplied by ``scale``.  The coordinate :math:`j` of 
+``scale`` and ``offset`` is the coordinate of ``output`` projected onto ``axes``.
+
+Inputs
+------
+
++-----------------+-------------------------+---------------------------------------+
+| Name            | Element Type            | Shape                                 |
++=================+=========================+=======================================+
+| ``input``       | Any quantized type      | Any                                   |
++-----------------+-------------------------+---------------------------------------+
+| ``scale``       | Same as ``output``      | ``input`` shape projected on ``axes`` |
++-----------------+-------------------------+---------------------------------------+
+| ``offset``      | Same as ``input``       | ``input`` shape projected on ``axes`` |
++-----------------+-------------------------+---------------------------------------+
+
+Attributes
+----------
+
++-------------------------------+----------------------------------------------------------------+
+| Name                          | Description                                                    |
++===============================+================================================================+
+| ``type``                      | ``output`` element type                                        |
++-------------------------------+----------------------------------------------------------------+
+| ``axes``                      | Axis positions on which ``scale`` and ``offset`` are specified |
++-------------------------------+----------------------------------------------------------------+
+
+
+
+Outputs
+-------
+
++-----------------+-------------------------+---------------------------------------+
+| Name            | Element Type            | Shape                                 |
++=================+=========================+=======================================+
+| ``output``      | is_real()               | Same as ``input``                     |
++-----------------+-------------------------+---------------------------------------+
+
+Mathematical Definition
+=======================
+
+.. math::
+
+   \mathtt{output}_{i} = (\mathtt{input}_{i} + \mathtt{offset}_{j}) \mathtt{scale}_{j}
+
+
+C++ Interface
+=============
+
+.. doxygenclass:: ngraph::op::Dequantize
+   :project: ngraph
+   :members: 

doc/sphinx/source/ops/index.rst

@@ -65,6 +65,7 @@ Not currently a comprehensive list.
    * :doc:`convolution`
    * :doc:`cos`
    * :doc:`cosh`
+   * :doc:`dequantize`
    * :doc:`divide`
    * :doc:`dot`
    * :doc:`drop_out`
@@ -93,6 +94,7 @@ Not currently a comprehensive list.
    * :doc:`parameter`
    * :doc:`power`
    * :doc:`product`
+   * :doc:`quantize`
    * :doc:`relu`
    * :doc:`result`
    * :doc:`sigmoid`
@@ -128,6 +130,7 @@ Not currently a comprehensive list.
    convolution.rst
    cos.rst
    cosh.rst
+   dequantize.rst
    divide.rst
    dot.rst
    drop_out.rst
@@ -156,6 +159,7 @@ Not currently a comprehensive list.
    parameter.rst
    power.rst
    product.rst
+   quantize.rst
    relu.rst
    result.rst
    sigmoid.rst

doc/sphinx/source/ops/quantize.rst

+.. quantize.rst: 
+
+########
+Quantize
+########
+
+.. code-block:: cpp
+
+   Quantize // Maps real input to quantized output
+
+Description
+===========
+
+Produces a tensor of element type ``type`` and the same shape as ``input``
+where the value of each coordinate :math:`i` of ``output`` is the corresponding 
+coordinate of ``input`` divided by ``scale`` rounded as specified by 
+``round_mode`` minus ``offset``. The coordinate :math:`j` of ``scale`` and 
+``offset`` is the coordinate of ``output`` projected onto ``axes``.
+
+Inputs
+------
+
++-----------------+-------------------------+---------------------------------------+
+| Name            | Element Type            | Shape                                 |
++=================+=========================+=======================================+
+| ``input``       | is_real()               | Any                                   |
++-----------------+-------------------------+---------------------------------------+
+| ``scale``       | Same as ``input``       | ``input`` shape projected on ``axes`` |
++-----------------+-------------------------+---------------------------------------+
+| ``offset``      | Same as ``output``      | ``input`` shape projected on ``axes`` |
++-----------------+-------------------------+---------------------------------------+
+
+Attributes
+----------
+
++-------------------------------+----------------------------------------------------------------+
+| Name                          | Description                                                    |
++===============================+================================================================+
+| ``type``                      | The output element type, which must be a quantized type        |
++-------------------------------+----------------------------------------------------------------+
+| ``axes``                      | Axis positions on which ``scale`` and ``offset`` are specified |
++-------------------------------+----------------------------------------------------------------+
+| ``round_mode``                | Refer to ``/src/ngraph/op/quantize.hpp``                       |
++-------------------------------+----------------------------------------------------------------+
+
+
+
+Outputs
+-------
+
++-----------------+-------------------------+---------------------------------------+
+| Name            | Element Type            | Shape                                 |
++=================+=========================+=======================================+
+| ``output``      | type                    | Same as ``input``                     |
++-----------------+-------------------------+---------------------------------------+
+
+Mathematical Definition
+=======================
+
+.. math::
+  
+   \mathtt{output}_{i} = \mathtt{round}(\frac{\mathtt{input}_{i}}{\mathtt{scale}_{j}}) - \mathtt{offset}_{j}    
+
+
+
+C++ Interface
+=============
+
+.. doxygenclass:: ngraph::op::Quantize
+   :project: ngraph
+   :members: 

src/ngraph/op/dequantize.hpp

@@ -24,9 +24,18 @@ namespace ngraph
 {
     namespace op
     {
+        /// \brief Dequantize operation
+        ///        Maps quantized input (q) to real output (r) using scale (s) and offset (o)
+        ///        q = (r + o) * s
         class Dequantize : public ngraph::op::Op
         {
         public:
+            /// \brief Constructs a Dequantize operation
+            /// \param input quantized input
+            /// \param scale element type: same as `type`, shape: input shape projected along `axes`
+            /// \param offset element type: same as `input`, shape: input shape projected along `axes`
+            /// \param type output element type
+            /// \param axes axis positions on which `scale` and `offset` are specified
             Dequantize(std::shared_ptr<Node> input,
                        std::shared_ptr<Node> scale,
                        std::shared_ptr<Node> offset,

src/ngraph/op/quantize.hpp

@@ -24,15 +24,29 @@ namespace ngraph
 {
     namespace op
     {
+        /// \brief Quantize operation
+        ///        Maps real input (r) to quantized output (q) using scale (s), offset (o) and round mode
+        ///        q = ROUND(r / s) - o
         class Quantize : public ngraph::op::Op
         {
         public:
             enum class RoundMode
             {
+                // -3.5 -> 4
+                // 2.5 -> 3
                 HALF_AWAY_FROM_ZERO,
+                // -3.5 -> 4
+                // 2.5 -> 2 (nearest even)
                 HALF_TO_EVEN
             };
 
+            /// \brief Constructs a Quantize operation
+            /// \param input real input
+            /// \param scale element type: same as `input`, shape: `input` shape projected along `axes`
+            /// \param offset element type: same as `type`, shape: `input` shape projected along `axes`
+            /// \param type output element type
+            /// \param axes axis positions on which `scale` and `offset` are specified
+            /// \param round_mode describes how to perform ROUND function
             Quantize(std::shared_ptr<Node> input,
                      std::shared_ptr<Node> scale,
                      std::shared_ptr<Node> offset,