diff --git a/doc/sphinx/ngraph_theme/static/css/theme.css b/doc/sphinx/ngraph_theme/static/css/theme.css
index 3c4cb1f1c9d..ab4bc961415 100644
--- a/doc/sphinx/ngraph_theme/static/css/theme.css
+++ b/doc/sphinx/ngraph_theme/static/css/theme.css
@@ -49,24 +49,19 @@ div.menu-float {
text-align: center;
background: #393F4D;
opacity: 0.9717;
- /* margin-left: 55%; */
- /* margin-right: 3%; */
padding: 3px;
border-top: 1px solid #999999;
border-left: 1px solid #999999;
border-right: 1px solid #999999;
margin-top: -2px;
margin-left: -2px;
- /* -moz-box-shadow: 2px 3px 2px #d3d3d3; */
- /* -webkit-box-shadow: 2px 3px 2px #d3d3d3 */
- /* box-shadow: 3px 4px 3px #d3d3d3; */
-webkit-border-radius: 0.1px;
-moz-border-radius: 0.1px;
border-radius: 0.1px;
z-index:1000;
}
-div.menu-float a, div.floating-menu h3 {display:inline-block; margin:0 0.5em; font-size: 143%; line-height: 1.41em; color: #fcfcfc; }
+div.menu-float a, div.floating-menu h3 {display:inline-block; margin:0 0.5em; font-size: 133%; line-height: 1.31em; color: #fcfcfc; }
#nav {
@@ -1535,7 +1530,7 @@ a:hover {
}
a:visited {
- color: #FFA400;
+ color: #DC700D;
}
html {
@@ -1644,7 +1639,6 @@ h1 {
h2 {
font-size: 133%;
- text-decoration: underline 4px dotted #D3D3D3;
margin-top: -2px;
}
@@ -1761,7 +1755,7 @@ div[class^='highlight'] td.code {
.wy-menu-vertical p.caption {
font-family: Nunito, 'Nunito Sans', Helvetica, 'Helvetica Neue', sans;
- text-decoration: underline 2px #393F4D;
+ /* text-decoration: underline 2px #393F4D; */
font-size: 110%;
color: #23221d;
background-color: #FAFBFD;
@@ -2215,6 +2209,10 @@ div[class^='highlight'] pre {
padding: 6px;
color: #FDC939;
}
+.rst-other-versions a:hover {
+ color: #555;
+ background-color: #e0e0e0;
+}
.rst-versions.rst-badge {
width: auto;
bottom: 20px;
@@ -2430,7 +2428,6 @@ div[class^='highlight'] pre {
.rst-content tt.literal, .rst-content tt.literal, .rst-content code.literal {
font-size: 91% !important;
color: #152a58;
- text-decoration: underline 2px dotted #cdcac5;
background-color: #fff;
line-height: 0.8955em;
}
@@ -2666,7 +2663,7 @@ span[id*='MathJax-Span'] {
font-family: 'Nunito Sans', Nunito, Helvetica, 'Helvetica Neue', sans;
font-weight: bolder;
border-top: 5px dotted #FFA400;
- border-bottom: 29px solid #d3d3d3;
+ border-bottom: 28px solid #d3d3d3;
font-size: 131%;
color: #393F4D;
width: auto;
@@ -2816,15 +2813,12 @@ span[id*='MathJax-Span'] {
}
.wy-menu-vertical a:hover {
background-color: #fafbfd;
- text-decoration: underline 1.33em dotted;
- cursor: pointer;
}
.wy-menu-vertical a:hover span.toctree-expand {
color: #e8e8e8;
}
.wy-menu-vertical a:active {
background-color: #FAFBFD;
- cursor: pointer;
color: #555;
}
.wy-menu-vertical a:active span.toctree-expand {
diff --git a/doc/sphinx/source/backends/index.rst b/doc/sphinx/source/backends/index.rst
index c07988f389c..d4472f9c857 100644
--- a/doc/sphinx/source/backends/index.rst
+++ b/doc/sphinx/source/backends/index.rst
@@ -51,7 +51,7 @@ How to use?
#. A single iteration of the executable is executed by calling the ``call``
method on the ``Executable`` object.
-.. figure:: ../graphics/ExecutionInterfaceRunGraphs.png
+.. figure:: ../graphics/execution-interface-run-graph.svg
:width: 650px
The execution interface for nGraph
diff --git a/doc/sphinx/source/buildlb.rst b/doc/sphinx/source/buildlb.rst
index 6e89c65d6e1..8f4eeca9fa5 100644
--- a/doc/sphinx/source/buildlb.rst
+++ b/doc/sphinx/source/buildlb.rst
@@ -106,7 +106,7 @@ The process documented here will work on Ubuntu\* 16.04 (LTS) or on Ubuntu
.. code-block:: console
- $ cmake .. [-DNGRAPH_USE_PREBUILT_LLVM=OFF] [-DNGRAPH_TARGET_ARCH=skylake-avx512]
+ $ cmake .. [-DNGRAPH_TARGET_ARCH=skylake-avx512]
#. Run ``$ make`` and ``make install`` to install ``libngraph.so`` and the
header files to ``~/ngraph_dist``:
diff --git a/doc/sphinx/source/core/constructing-graphs/distribute-train.rst b/doc/sphinx/source/core/constructing-graphs/distribute-train.rst
index 96d6dc0fdb2..4f6f0fd57ac 100644
--- a/doc/sphinx/source/core/constructing-graphs/distribute-train.rst
+++ b/doc/sphinx/source/core/constructing-graphs/distribute-train.rst
@@ -33,7 +33,7 @@ Finally, to run the training using two nGraph devices, invoke
.. code-block:: console
- $ mpirun
+ mpirun
To deploy data-parallel training, the ``AllReduce`` op should be added after the
steps needed to complete the :doc:`backpropagation <../constructing-graphs/derive-for-training>`;
@@ -48,7 +48,7 @@ See the `full code`_ in the ``examples`` folder ``/doc/examples/mnist_mlp/dist_m
.. code-block:: console
- $ mpirun -np 2 dist_mnist_mlp
+ mpirun -np 2 dist_mnist_mlp
.. _Intel MLSL: https://github.com/intel/MLSL/releases
diff --git a/doc/sphinx/source/core/constructing-graphs/execute.rst b/doc/sphinx/source/core/constructing-graphs/execute.rst
index a53cb6bacbf..491c215218b 100644
--- a/doc/sphinx/source/core/constructing-graphs/execute.rst
+++ b/doc/sphinx/source/core/constructing-graphs/execute.rst
@@ -5,17 +5,40 @@ Execute a computation
######################
This section explains how to manually perform the steps that would normally be
-performed by a framework :term:`bridge` to execute a computation. The nGraph
-library is targeted toward automatic construction; it is far easier for a
-processing unit (GPU, CPU, or an `Intel Nervana NNP`_) to run a computation than
-it is for a human to map out how that computation happens. Unfortunately, things
+performed by a framework :term:`bridge` to execute a computation. nGraph graphs
+are targeted toward automatic construction; it is far easier for a processor
+(a CPU, GPU, or `purpose-built silicon`_) to execute a computation than it is
+for a human to map out how that computation happens. Unfortunately, things
that make by-hand graph construction simpler tend to make automatic construction
more difficult, and vice versa.
-Here we will do all the bridge steps manually. The :term:`model description`
-walk-through below is based on the :file:`abc.cpp` code in the ``/doc/examples/``
-directory. We'll be deconstructing the steps that must happen (either programmatically
-or manually) in order to successfully execute a computation:
+Nevertheless, it can be helpful to break down what is happening during graph
+construction. The documetation that follows explains two approaches frameworks
+can use to compile with nGraph operations:
+
+* :ref:`Using complete shapes `
+* :ref:`Using partial shapes `
+
+The nGraph :abbr:`Intermediate Representation (IR)` uses a strong, dynamic
+type system, including static shapes. This means that at compilation, every
+tensor (or, equivalently, every node output) in the graph is assigned
+**complete shape information**; that is, one and only one shape. The static
+process by which this assignment takes place is called :term:`shape propagation`.
+
+In the :ref:`first scenario `, the :term:`model description`
+walk-through is based on the :file:`abc.cpp` code in the ``/doc/examples/abc``
+directory, and it deconstructs the steps that must happen (either programmatically
+or manually) in order to successfully execute a computation given complete
+shape information.
+
+.. _scenario_one:
+
+Scenario One: Using Complete Shapes
+===================================
+
+A step-by-step example of how a framework might execute with complete shape
+information is provided here. For a step-by-step example using dynamic
+shapes, see :ref:`scenario_two`.
* :ref:`define_cmp`
* :ref:`specify_backend`
@@ -25,13 +48,11 @@ or manually) in order to successfully execute a computation:
* :ref:`invoke_cmp`
* :ref:`access_outputs`
-The full code is at the :ref:`end of this page `.
-
.. _define_cmp:
Define the computation
-======================
+----------------------
To a :term:`framework`, a computation is simply a transformation of inputs to
outputs. While a :term:`bridge` can programmatically construct the graph
@@ -111,10 +132,10 @@ function, in the order they are to be passed to the compiled function. A
.. _specify_backend:
Specify the backend upon which to run the computation
-=====================================================
+-----------------------------------------------------
For a framework bridge, a *backend* is the environment that can perform the
-computations; it can be done with a CPU, GPU, or an Intel Nervana NNP. A
+computations; it can be done with a CPU, GPU, or `purpose-built silicon`_. A
*transformer* can compile computations for a backend, allocate and deallocate
tensors, and invoke computations.
@@ -123,7 +144,7 @@ and allocate backends. A backend is somewhat analogous to a multi-threaded
process.
There are two backends for the CPU: the optimized ``"CPU"`` backend, which uses
-the `Intel MKL-DNN`_, and the ``"INTERPRETER"`` backend, which runs reference
+the `DNNL`_, and the ``"INTERPRETER"`` backend, which runs reference
versions of kernels that favor implementation clarity over speed. The
``"INTERPRETER"`` backend can be slow, and is primarily intended for testing.
See the documentation on :doc:`runtime options for various backends <../../backends/index>`
@@ -139,7 +160,7 @@ To continue with our original example and select the ``"CPU_Backend"``:
.. _compile_cmp:
Compile the computation
-=======================
+-----------------------
Compilation triggers something that can be used as a factory for producing a
``CallFrame`` which is a *function* and its associated *state* that can run
@@ -152,7 +173,7 @@ thread needs to execute the function at the same time, create multiple
.. _allocate_backend_storage:
Allocate backend storage for the inputs and outputs
-===================================================
+---------------------------------------------------
At the graph level, functions are stateless. They do have internal state related
to execution, but there is no user-visible state. Variables must be passed as
@@ -182,7 +203,7 @@ with ``Tensor``.
.. _initialize_inputs:
Initialize the inputs
-=====================
+---------------------
Next we need to copy some data into the tensors.
@@ -196,7 +217,7 @@ copying data to/from the tensor.
.. _invoke_cmp:
Invoke the computation
-======================
+----------------------
To invoke the function, we simply pass argument and resultant tensors to the
call frame:
@@ -209,7 +230,7 @@ call frame:
.. _access_outputs:
Access the outputs
-==================
+------------------
We can use the ``read`` method to access the result:
@@ -217,10 +238,10 @@ We can use the ``read`` method to access the result:
:language: cpp
:lines: 60-77
-.. _all_together:
+.. _sshp:
-Put it all together
-===================
+Compiling with Complete Shape Information
+-----------------------------------------
.. literalinclude:: ../../../../examples/abc/abc.cpp
:language: cpp
@@ -228,7 +249,96 @@ Put it all together
:caption: "The (a + b) * c example for executing a computation on nGraph"
+.. _scenario_two:
+
+Scenario Two: Known Partial Shape
+=================================
+
+The :ref:`second scenario ` involves the use of dynamic tensors.
+A :term:`dynamic tensor` is a tensor whose shape can change from one "iteration"
+to the next. When a dynamic tensor is created, a framework :term:`bridge` might
+supply only *partial* shape information: it might be **all** the tensor
+dimensions, **some** of the tensor dimensions, or **none** of the tensor
+dimensions; furthermore, the rank of the tensor may be left unspecified.
+The "actual" shape of the tensor is not specified until some function writes
+some value to it. The actual shape can change when the value of the tensor
+is overwritten. It is the backend’s responsibility to set the actual shape.
+The :term:`model description` for the second scenario based on the
+:file:`partial_shape.cpp` code in the ``/doc/examples/dynamic_tensor``
+directory, and it deconstructs the steps that must happen (either
+programmatically or manually) in order to successfully retreive shape data.
+
+* :ref:`create_dyn_tensor`
+* :ref:`call_graph_vw_`
+* :ref:`call_graph_vwnew`
+* :ref:`kpsh`
+
+
+Create and compile a graph for ``f(x) = x + x`` where the provided info
+of shape ``x`` is ``(2,?)``:
+
+.. literalinclude:: ../../../../examples/dynamic_tensor/partial_shape.cpp
+ :language: cpp
+ :lines: 27-32
+
+
+.. _create_dyn_tensor:
+
+Create a dynamic tensor
+-----------------------
+
+Create a dynamic tensor of shape ``(2,?)``
+
+.. literalinclude:: ../../../../examples/dynamic_tensor/partial_shape.cpp
+ :language: cpp
+ :lines: 35
+
+At this point, ``t_out->get_shape()`` would throw an exception, while
+``t_out->get_partial_shape()`` would return ``"(2,?)"``.
+
+
+.. _call_graph_vw_:
+
+Write shape
+-----------
+
+Call the graph to write a value with shape (2,3) to t_out
+
+.. literalinclude:: ../../../../examples/dynamic_tensor/partial_shape.cpp
+ :language: cpp
+ :lines: 38-40
+
+At this point, ``t_out->get_shape()`` would return ``Shape{2,3}``,
+while ``t_out->get_partial_shape()`` would return ``"(2,?)"``.
+
+
+.. _call_graph_vwnew:
+
+Write new shape
+---------------
+
+Call the graph again, to write a value with a different shape to ``t_out``.
+
+.. literalinclude:: ../../../../examples/dynamic_tensor/partial_shape.cpp
+ :language: cpp
+ :lines: 44-45
+
+At this point, ``t_out->get_shape()`` would return ``Shape{2,20}``,
+while ``t_out->get_partial_shape()`` would return ``"(2,?)"``.
+
+
+.. _kpsh:
+
+Compiling with Known Partial Shape
+----------------------------------
+
+.. literalinclude:: ../../../../examples/dynamic_tensor/partial_shape.cpp
+ :language: cpp
+ :linenos:
+ :caption: "Full code for compiling with dynamic tensors and partial shape"
+
+
+.. _purpose-built silicon: https://www.intel.ai/nervana-nnp
+.. _DNNL: https://intel.github.io/mkl-dnn/
-.. _Intel MKL-DNN: https://01.org/mkl-dnn
-.. _Intel Nervana NNP: https://ai.intel.com/intel-nervana-neural-network-processors-nnp-redefine-ai-silicon/
diff --git a/doc/sphinx/source/core/constructing-graphs/index.rst b/doc/sphinx/source/core/constructing-graphs/index.rst
index 16a90ecd40c..e618dc8e0b5 100644
--- a/doc/sphinx/source/core/constructing-graphs/index.rst
+++ b/doc/sphinx/source/core/constructing-graphs/index.rst
@@ -30,34 +30,5 @@ resources, it can either:
.. note:: This section is aimed at intermediate-level developers. It assumes an
understanding of the concepts in the previous sections. It does not assume
- knowledge of any particular frontend framework.
-
-Since our primary audience is developers who are pushing the boundaries of deep
-learning systems, we go beyond the use of deep learning primitives, and include
-APIs and documentation for developers who want the ability to write programs
-that use custom backends. For example, we know that GPU resources can be useful
-backends for *some* kinds of algorithmic operations while they impose inherent
-limitations or slow down others.
-
-One of our goals with the nGraph library is to enable developers with tools to
-quickly build programs that access and process data from a breadth of edge and
-networked devices. This might mean bringing compute resources closer to edge
-devices, or it might mean programatically adjusting a model or the compute
-resources it requires, at an unknown or arbitrary time after it has been deemed
-to be trained well enough.
-
-To get started, we've provided a basic example for how to :doc:`execute` a
-computation that can run on an nGraph backend; this is analogous to a
-framework bridge. We also provide a larger example for training and
-evaluating a simple MNIST MLP model.
-
-For data scientists or algorithm developers who are trying to extract specifics
-about the state of a model at a certain node, or who want to optimize a model
-at a more granular level, we provide an example for how to :doc:`import` and
-run inference after it has been exported from a DL framework.
-
-This section is under development; we'll continually populate it with more
-articles geared toward data scientists, algorithm designers, framework developers,
-backend engineers, and others. We welcome ideas and contributions from the
-community.
+ knowledge of any particular frontend framework.
diff --git a/doc/sphinx/source/core/overview.rst b/doc/sphinx/source/core/overview.rst
index e873ccbb036..5c04219f803 100644
--- a/doc/sphinx/source/core/overview.rst
+++ b/doc/sphinx/source/core/overview.rst
@@ -1,7 +1,7 @@
.. core/overview.rst:
-Basic concepts
+Basic Concepts
==============
.. figure:: ../graphics/nGraphCompilerstack.png
diff --git a/doc/sphinx/source/core/passes/passes.rst b/doc/sphinx/source/core/passes/passes.rst
index 0658c70bd6b..d9b591d3cad 100644
--- a/doc/sphinx/source/core/passes/passes.rst
+++ b/doc/sphinx/source/core/passes/passes.rst
@@ -62,7 +62,7 @@ hardware-specific primitives; here they get matched via Intel® MKL-DNN.
.. _figure-simple-compiler:
-.. figure:: ../../graphics/simple-compiler-passes.png
+.. figure:: ../../graphics/simple-compiler-passes.svg
:width: 750px
:alt: Simple kernel fusion
diff --git a/doc/sphinx/source/core/quantization.rst b/doc/sphinx/source/core/quantization.rst
new file mode 100644
index 00000000000..51bb7432a55
--- /dev/null
+++ b/doc/sphinx/source/core/quantization.rst
@@ -0,0 +1,169 @@
+.. core/quantization.rst:
+
+
+.. _quantization:
+
+Quantization
+============
+
+:term:`Quantization` refers the process of reducing the number of bits that
+represent a number. In a :abbr:`DL (Deep Learning)` context, weights and
+activations can be represented using 8-bit integers (INT8) to compress the
+model size of a trained neural network without any significant loss in model
+accuracy. INT8 is one kind of quantization. Compared with 32-bit floating point
+(FP32), using arithmetic with lower precision, such as INT8, to calculate
+weights and activation requires less memory.
+
+
+Implementing a quantized model with nGraph
+------------------------------------------
+
+To implement a quantized model with nGraph, provide a partially (or fully)
+quantized model (where the convolution layer in the model is replaced
+with a quantized convolution, for example) to the nGraph Library along with
+quantized parameters: weights, activations, scale, and zero point.
+
+.. note:: As of version |version|, only quantization for inference is supported.
+
+nGraph Quantized Operators (Ops)
+--------------------------------
+
+nGraph uses scale and zero point (also used by ONNX) to map real values to
+quantized values. All quantized ops use scale and zero point
+and can be used just like any other nGraph op.
+
+**Scale**: the quantization scale of the tensor
+
+**Zero point**: the zero point of the tensor
+
+**Round mode**: used in combination with scale and zero point to round real
+values to quantized values
+
+.. table:: Quantization Ops
+
+
+ +-----------------------------------------------------------------+------------------------------------------------+
+ | Op | Description |
+ +=================================================================+================================================+
+ | :doc:`Quantize <../ops/quantize>` | Maps real values (r) to quantized values (q) |
+ | | using scale (s), zero point (z), |
+ | | and round mode; produces a quantized tensor. |
+ +-----------------------------------------------------------------+------------------------------------------------+
+ | :doc:`Dequantize <../ops/dequantize>` | Maps quantized values (q) to real values (r) |
+ | | using scale (s) and zero point (z); converts |
+ | | a quantized tensor to a floating-point tensor. |
+ +-----------------------------------------------------------------+------------------------------------------------+
+ | :mod:`FakeQuantize ` | Performs element-wise linear quantization. |
+ +-----------------------------------------------------------------+------------------------------------------------+
+ | :mod:`QuantizedConvolution ` | Performs 8-bit convolution. |
+ +-----------------------------------------------------------------+------------------------------------------------+
+ | :mod:`QuantizedDot ` | Performs 8-bit dot. |
+ +-----------------------------------------------------------------+------------------------------------------------+
+
+Some frameworks such as TensorFlow\* have fused ops. nGraph provides optional
+operations to help users easily translate (map) any quantized model created from
+frameworks with fused ops to nGraph. Unlike builders, experimental ops take
+scale and zero point instead of min and max.
+
+.. table:: Experimental Quantized Ops (optional)
+
+
+ +-----------------------------------+-------------------------------------+
+ | Operator | Description |
+ +===================================+=====================================+
+ | QuantizedConvolutionBias | This experimental op can be |
+ | | fused with a ReLU op. |
+ +-----------------------------------+-------------------------------------+
+ | QuantizedConvolutionBiasAdd | This experimental op constructs a |
+ | | quantized convolution with bias and |
+ | | optional ReLU. And then takes input |
+ | | for the add operation. |
+ +-----------------------------------+-------------------------------------+
+ | QuantizedConvolutionBiasSignedAdd | Same as QuantizedConvolutionBiasAdd |
+ | | but with signed add. |
+ +-----------------------------------+-------------------------------------+
+ | QuantizedConvolutionRelu | This experimental op is designed |
+ | | for a particular use case that |
+ | | would require convolution |
+ | | and ReLU to be combined. |
+ +-----------------------------------+-------------------------------------+
+ | QuantizedDotBias | This experimental op can be fused |
+ | | with a ReLU op. |
+ +-----------------------------------+-------------------------------------+
+
+nGraph Quantization Design
+--------------------------
+
+The goal of nGraph quantization is to flexibly support a wide variety of
+frameworks and users. The use of scale and zero point as well as quantized
+builders in the nGraph design helps to achieve this goal.
+
+Scale and Zero Point
+~~~~~~~~~~~~~~~~~~~~
+
+Using scale and zero point allows nGraph to be framework agnostic (i.e., it
+can equally support all deep learning frameworks). nGraph Bridges will
+automatically convert min and max (provided by a DL framework) to scale and zero
+point as needed. Quantized builders are available to help the bridges perform
+this calculation. However, if users are directly using nGraph (and not using a
+bridge), they are required to provide scale and zero point for quantized ops.
+
+Another advantage of using scale and zero point to express quantization
+parameters is that users can flexibly implement quantized ops into various
+nGraph backends. When implementing quantized ops, all current nGraph backends
+will directly use scale and zero point (and not min and max) to perform
+the quantized computation.
+
+Quantized Builders
+~~~~~~~~~~~~~~~~~~
+
+Quantized builders are helper utilities to assist framework integrators to
+enable quantized models with nGraph. They serve as an API (interface) between
+framework bridges and nGraph, allowing framework bridges to directly construct
+ops in the nGraph Abstraction Layer.
+
+Quantized builders help nGraph framework bridges by:
+
+* Breaking down a fused quantized operator in the framework to a subgraph (of
+ quantized and non-quantized operators) in the nGraph core IR
+
+* Converting from min and max to scale and zero point based on the quantization
+ mode described by the DL framework
+
+.. note:: Fused ops and quantized builders serve the same purpose.
+ In the future, fused ops will replace quantized builders.
+
+.. table:: nGraph Quantized Builders
+
+ +--------------------------+-----------------------------------+-----------------------------------------+
+ | Category | Builder | Description |
+ +==========================+===================================+=========================================+
+ | Scaled Mode | ScaledQuantize | Converts min and max to scale |
+ | Min / Max Builders | | and zero point using a scaled mode |
+ | | | calculation and then constructs and |
+ | | | returns an nGraph Quantize operator. |
+ | +-----------------------------------+-----------------------------------------+
+ | | ScaledDequantize | Converts min and max to scale |
+ | | | and zero point using a scaled mode |
+ | | | calculation and then constructs and |
+ | | | returns an nGraph Dequantize operator. |
+ +--------------------------+-----------------------------------+-----------------------------------------+
+ | Quantized Convolution | ScaledQuantizedConvolution | Constructs a quantized convolution |
+ | and Variants | | with an optional ReLU. |
+ | +-----------------------------------+-----------------------------------------+
+ | | ScaledQuantizedConvolutionBias | Constructs a quantized convolution |
+ | | | with bias and an optional ReLU. |
+ | +-----------------------------------+-----------------------------------------+
+ | | ScaledQuantizedConvolutionBiasAdd | Constructs a quantized convolution |
+ | | | with bias and an optional ReLU, where |
+ | | | the output is added to the output |
+ | | | of another convolution (sum_input). |
+ +--------------------------+-----------------------------------+-----------------------------------------+
+ | Quantized Dot (Matmul) | ScaledQuantizedDot | Constructs a quantized dot (Matmul) |
+ | and Variants | | with an optional ReLU. |
+ | +-----------------------------------+-----------------------------------------+
+ | | ScaledQuantizedDotBias | Constructs a quantized dot (Matmul) |
+ | | | with bias and an optional ReLU. |
+ +--------------------------+-----------------------------------+-----------------------------------------+
+ | Quantized Concat | ScaledQuantizedConcat | Constructs a quantized concatenation. |
+ +--------------------------+-----------------------------------+-----------------------------------------+
diff --git a/doc/sphinx/source/dynamic/index.rst b/doc/sphinx/source/dynamic/index.rst
new file mode 100644
index 00000000000..7808eabf961
--- /dev/null
+++ b/doc/sphinx/source/dynamic/index.rst
@@ -0,0 +1,41 @@
+.. dynamic/index.rst:
+
+
+Dynamic Shapes
+==============
+
+For an example on how to use dynamic shapes, see the :ref:`scenario_two`
+documentation.
+
+Runtime Error Checking
+----------------------
+
+Static type-checking in the presence of dynamic shapes will make optimistic
+assumptions about things like shape mismatches. For example, if an elementwise
+op is provided inputs of shapes ``(2,?)`` and ``(?,5)``, the type checker will
+proceed under the assumption that the user is not going to pass tensors with
+inconsistent shape at runtime, and therefore infer an output shape of ``(2,5)``.
+That means that shape mismatches can now occur at runtime.
+
+
+.. _partial_shapes:
+
+PartialShape, Dimension, and Rank Classes
+-----------------------------------------
+
+Partial shape information is expressed via the ``PartialShape``, ``Dimension``,
+and ``Rank`` classes.
+
+.. note:: ``Rank`` is an alias for ``Dimension``, used when the value represents
+ the number of axes in a shape, rather than the size of one dimension in a shape.
+
+
+.. doxygenclass:: ngraph::PartialShape
+ :project: ngraph
+ :members:
+
+
+.. doxygenclass:: ngraph::Dimension
+ :project: ngraph
+ :members:
+
diff --git a/doc/sphinx/source/frameworks/index.rst b/doc/sphinx/source/frameworks/index.rst
index a87d7622f0d..a1eaaf4bdae 100644
--- a/doc/sphinx/source/frameworks/index.rst
+++ b/doc/sphinx/source/frameworks/index.rst
@@ -1,3 +1,5 @@
+:orphan:
+
.. frameworks/index.rst
Working with Frameworks
@@ -11,4 +13,4 @@ Working with Frameworks
onnx_integ.rst
paddle_integ.rst
tensorflow_connect.rst
- other.rst
+ other/index.rst
diff --git a/doc/sphinx/source/frameworks/onnx_integ.rst b/doc/sphinx/source/frameworks/onnx_integ.rst
index db40ed7262d..6c4739d6c9c 100644
--- a/doc/sphinx/source/frameworks/onnx_integ.rst
+++ b/doc/sphinx/source/frameworks/onnx_integ.rst
@@ -1,7 +1,7 @@
.. frameworks/onnx_integ.rst:
-ONNX overview
-=============
+ONNX
+====
nGraph is able to import and execute ONNX models. Models are converted to
nGraph's :abbr:`Intermediate Representation (IR)` and converted to ``Function``
diff --git a/doc/sphinx/source/frameworks/other.rst b/doc/sphinx/source/frameworks/other/index.rst
similarity index 93%
rename from doc/sphinx/source/frameworks/other.rst
rename to doc/sphinx/source/frameworks/other/index.rst
index f9c9809db97..d3bae434f3b 100644
--- a/doc/sphinx/source/frameworks/other.rst
+++ b/doc/sphinx/source/frameworks/other/index.rst
@@ -1,16 +1,18 @@
-.. frameworks/other.rst:
+.. frameworks/other/index.rst:
.. _fw_other:
+.. contents::
+
Integrating other frameworks
============================
This section details some of the *configuration options* and some of the
*environment variables* that can be used to tune for optimal performance when
your system already has a version of nGraph installed with one or more of our
-supported :doc:`../backends/index`.
+supported :doc:`../../backends/index`.
-Regardless of the framework, after the :doc:`../buildlb` step, a good place
+Regardless of the framework, after the :doc:`../../buildlb` step, a good place
to start usually involves making the libraries available to the framework. On
Linux\* systems built on Intel® Architecture, that command tends to looks
something like:
@@ -24,7 +26,7 @@ something like:
Find or display version
-----------------------
-If you're working with the :doc:`../python_api/index`, the following command
+If you're working with the :doc:`../../python_api/index`, the following command
may be useful:
.. code-block:: console
@@ -92,10 +94,10 @@ Training Deep Neural Networks
-----------------------------
Before tweaking various environment variables, be aware that how the computation
-gets executed depends upon the ordering of the data format that the model is
-using. ``NHWC`` and ``NCHW`` are the two more common layouts in Deep Learning
-models. Your ultimate runtime can vary greatly -- even when all other factors
-are exactly the same -- when this detail is overlooked.
+gets executed depends on the data layout that the model is using. ``NHWC`` and
+``NCHW`` are common layouts in Deep Learning models. Your ultimate
+runtime can vary greatly -- even when all other factors are exactly the same --
+when this detail is overlooked.
For CPU (and most cuDNN) backends, the preferred layout is currently ``NCHW``.
@@ -110,7 +112,7 @@ Intel® Math Kernel Library for Deep Neural Networks
---------------------------------------------------
.. important:: Intel® MKL-DNN is automatically enabled as part of an
- nGraph default :doc:`build <../buildlb>`; you do *not* need to add it
+ nGraph default :doc:`build <../../buildlb>`; you do *not* need to add it
separately or as an additional component to be able to use these
configuration settings.
@@ -229,4 +231,3 @@ thus can make more efficient use of the underlying hardware.
.. _BUILDING.md: https://github.com/NervanaSystems/ngraph/blob/master/python/BUILDING.md
.. _GCC wiki for details: https://gcc.gnu.org/wiki/FunctionMultiVersioning
.. _following article may be helpful: https://clearlinux.org/documentation/clear-linux/tutorials/fmv
-
diff --git a/doc/sphinx/source/frameworks/overview.rst b/doc/sphinx/source/frameworks/overview.rst
index 1c2712f4690..da3312e3b7b 100644
--- a/doc/sphinx/source/frameworks/overview.rst
+++ b/doc/sphinx/source/frameworks/overview.rst
@@ -16,8 +16,9 @@ the nGraph Compiler, it helps to familiarize yourself with some basic concepts.
We use the term :term:`bridge` to describe code that connects to any nGraph
device backend(s) while maintaining the framework's programmatic or user
interface. We have a `bridge for the TensorFlow framework`_. We also have a
-:doc:`paddle_integ` bridge. Intel previously :doc:`contributed work to an MXNet bridge <../project/extras/testing_latency>`;
-however, support for the MXNet bridge is no longer active.
+:doc:`paddle_integ` bridge. Intel previously :doc:`contributed work to an MXNet
+bridge <../project/extras/testing_latency>`; however, support for the MXNet
+bridge is no longer active.
`ONNX`_ on its own is not a framework; it can be used with nGraph's
:doc:`../python_api/index` to import and execute ONNX models.
@@ -37,7 +38,7 @@ data scientists, or for deployment in cloud container environments, nGraph's
We invite anyone working on new and novel frameworks or neural network designs
to explore our highly-modularized stack of components.
-Please read the :doc:`other` section for other framework-agnostic
+Please read the :doc:`other/index` section for other framework-agnostic
configurations available to users of the nGraph Compiler stack.
.. figure:: ../graphics/overview-translation-flow.svg
diff --git a/doc/sphinx/source/frameworks/paddle_integ.rst b/doc/sphinx/source/frameworks/paddle_integ.rst
index 024ff424d7a..9c9d5ab76e0 100644
--- a/doc/sphinx/source/frameworks/paddle_integ.rst
+++ b/doc/sphinx/source/frameworks/paddle_integ.rst
@@ -1,7 +1,7 @@
.. frameworks/paddle_integ.rst:
-PaddlePaddle integration
-========================
+PaddlePaddle\*
+==============
PaddlePaddle is an open source deep learning framework developed by Baidu. It
aims to enable performant large-scale distributed computation for deep learning.
@@ -47,8 +47,8 @@ nGraph code in one place allows for easy maintenance.
.. _figure-paddle-design:
-.. figure:: ../graphics/paddlepaddle_design.png
- :width: 555px
+.. figure:: ../graphics/paddlepaddle_design.svg
+ :width: 100%
:alt:
*Figure A* above depicts nGraph access from PaddlePaddle. The PaddlePaddle
@@ -65,7 +65,7 @@ is organized in the following file structure:
.. _figure-paddle-dir:
.. figure:: ../graphics/PaddlePaddleDir.svg
- :width: 555px
+ :width: 100%
:alt:
Compilation of nGraph is handled by the ``ngraph.cmake`` file in the
diff --git a/doc/sphinx/source/frameworks/quickstart.rst b/doc/sphinx/source/frameworks/quickstart.rst
index 005258db9fa..ae4e3c8e278 100644
--- a/doc/sphinx/source/frameworks/quickstart.rst
+++ b/doc/sphinx/source/frameworks/quickstart.rst
@@ -79,7 +79,7 @@ Other integration paths
If you are considering incorporating components from the nGraph Compiler stack
in your framework or neural network design, another useful doc is the section
-on :doc:`other` . Contents here are also useful if you are working on
+on :doc:`other/index` . Contents here are also useful if you are working on
something built-from-scratch, or on an existing framework that is less
widely-supported than the popular frameworks like TensorFlow and PyTorch.
diff --git a/doc/sphinx/source/frameworks/tensorflow_connect.rst b/doc/sphinx/source/frameworks/tensorflow_connect.rst
index a73360210e4..5719ee0f67c 100644
--- a/doc/sphinx/source/frameworks/tensorflow_connect.rst
+++ b/doc/sphinx/source/frameworks/tensorflow_connect.rst
@@ -1,7 +1,7 @@
.. frameworks/tensorflow_connect.rst:
-nGraph Bridge for TensorFlow
-============================
+TensorFlow\*
+============
See the `README`_ on the `ngraph_bridge repo`_ for the many ways to connect
diff --git a/doc/sphinx/source/glossary.rst b/doc/sphinx/source/glossary.rst
index f6199a54d28..63e9e348096 100644
--- a/doc/sphinx/source/glossary.rst
+++ b/doc/sphinx/source/glossary.rst
@@ -101,11 +101,25 @@ Glossary
In the context of a function graph, the term "result" refers to
what stands in for the returned value.
+ dynamic tensor
+
+ A tensor whose shape can change from one "iteration" to the next. When
+ created, a framework :term:`bridge` might supply only *partial* shape
+ information: it might be **all** the tensor dimensions, **some** of the
+ tensor dimensions, or **none** of the tensor dimensions; furthermore,
+ the rank of the tensor may be left unspecified.
+
shape
The shape of a tensor is a tuple of non-negative integers that
represents an exclusive upper bound for coordinate values.
+ shape propagation
+
+ The static process by which assignment of every tensor (or,
+ equivalently, every node output) in the graph is assigned
+ **complete shape information**.
+
shared pointer
The C++ standard template library has the template
diff --git a/doc/sphinx/source/graphics/ExecutionInterfaceRunGraphs.png b/doc/sphinx/source/graphics/ExecutionInterfaceRunGraphs.png
deleted file mode 100644
index d3bfceacccfce034d49d82383c8c0fd017e8e1ad..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001
literal 43756
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