Skip to content

N
ngraph
Commit 3c830a69 authored by L.S. Cook's avatar L.S. Cook Committed by Scott Cyphers
Browse files
Options

Many updates to latest nGraph Architecture and feature docs (#1953) 

* editing docs

* more doc updates

* Cleanup theme, update backends for PlaidML, remove stale font

* Add PlaidML description and doc update that should have been added with PR 1888

* Add PlaidML description and doc update that should have been added with PR 1888

* Latest release doc updates

* Add PlaidML description and doc update for PR 1888
* Update glossary with tensor description and quantization def
* Refactor landpage with QuickStart guides
* Add better details about nGraph features and roadmap

* Placeholder detail for comparison section

* Add section link

* order sections alphabetically for now

* update compiler illustration

* Address feedback from doc review

* Update illustration wording

* Formatting and final edits

* keep tables consistent

* Clarify doc on bridge and compiler docs

* Clarify doc on bridge and compiler docs

* yay for more feedback and improvements

* edit with built doc

* Fix typo

* Another phase of PR review editing

* Final review comment resolved
parent 0bb9368a
Hide whitespace changes
Inline Side-by-side
Showing with 299 additions and 219 deletions
doc/sphinx/ngraph.doxyfile
View file @ 3c830a69
......@@ -15,8 +15,8 @@
PROJECT_NAME = "Intel® nGraph™ library API docs"
PROJECT_BRIEF = "C++ code reference for the Intel® nGraph™ library"
PROJECT_NAME = "Intel® nGraph Library and API docs"
PROJECT_BRIEF = "Code reference for the Intel® nGraph C++ Library"
OUTPUT_DIRECTORY = @CMAKE_CURRENT_BINARY_DIR@
INPUT = @CMAKE_SOURCE_DIR@/src
......@@ -1083,7 +1083,7 @@ HTML_EXTRA_FILES =
# Minimum value: 0, maximum value: 359, default value: 220.
# This tag requires that the tag GENERATE_HTML is set to YES.
HTML_COLORSTYLE_HUE = 220
HTML_COLORSTYLE_HUE = 193
# The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of the colors
# in the HTML output. For a value of 0 the output will use grayscales only. A
......@@ -1091,7 +1091,7 @@ HTML_COLORSTYLE_HUE = 220
# Minimum value: 0, maximum value: 255, default value: 100.
# This tag requires that the tag GENERATE_HTML is set to YES.
HTML_COLORSTYLE_SAT = 100
HTML_COLORSTYLE_SAT = 215
# The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to the
# luminance component of the colors in the HTML output. Values below 100
......@@ -1365,7 +1365,7 @@ ENUM_VALUES_PER_LINE = 8
# Minimum value: 0, maximum value: 1500, default value: 250.
# This tag requires that the tag GENERATE_HTML is set to YES.
TREEVIEW_WIDTH = 550
TREEVIEW_WIDTH = 248
# If the EXT_LINKS_IN_WINDOW option is set to YES, doxygen will open links to
# external symbols imported via tag files in a separate window.
......@@ -1381,7 +1381,7 @@ EXT_LINKS_IN_WINDOW = NO
# Minimum value: 8, maximum value: 50, default value: 10.
# This tag requires that the tag GENERATE_HTML is set to YES.
FORMULA_FONTSIZE = 10
FORMULA_FONTSIZE = 11
# Use the FORMULA_TRANPARENT tag to determine whether or not the images
# generated for formulas are transparent PNGs. Transparent PNGs are not
......@@ -1895,10 +1895,9 @@ HAVE_DOT = YES
# processors available in the system. You can set it explicitly to a value
# larger than 0 to get control over the balance between CPU load and processing
# speed.
# Minimum value: 0, maximum value: 32, default value: 0.
# This tag requires that the tag HAVE_DOT is set to YES.
DOT_NUM_THREADS = 0
DOT_NUM_THREADS = 32
# When you want a differently looking font in the dot files that doxygen
# generates you can specify the font name using DOT_FONTNAME. You need to make
......@@ -1908,21 +1907,21 @@ DOT_NUM_THREADS = 0
# The default value is: Helvetica.
# This tag requires that the tag HAVE_DOT is set to YES.
DOT_FONTNAME = NeoSansIntel
DOT_FONTNAME = "NeoSansIntel-Regular"
# The DOT_FONTSIZE tag can be used to set the size (in points) of the font of
# dot graphs.
# Minimum value: 4, maximum value: 24, default value: 10.
# This tag requires that the tag HAVE_DOT is set to YES.
DOT_FONTSIZE = 12
DOT_FONTSIZE = 10
# By default doxygen will tell dot to use the default font as specified with
# DOT_FONTNAME. If you specify a different font using DOT_FONTNAME you can set
# the path where dot can find it using this tag.
# This tag requires that the tag HAVE_DOT is set to YES.
DOT_FONTPATH = ngraph_theme/static/fonts/NeoSansIntel
DOT_FONTPATH = ngraph_theme/static/fonts/
# If the CLASS_GRAPH tag is set to YES then doxygen will generate a graph for
# each documented class showing the direct and indirect inheritance relations.
......@@ -2097,7 +2096,7 @@ DIAFILE_DIRS =
# Minimum value: 0, maximum value: 10000, default value: 50.
# This tag requires that the tag HAVE_DOT is set to YES.
DOT_GRAPH_MAX_NODES = 512
DOT_GRAPH_MAX_NODES = 1024
# The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the graphs
# generated by dot. A depth value of 3 means that only nodes reachable from the
......@@ -2109,7 +2108,7 @@ DOT_GRAPH_MAX_NODES = 512
# Minimum value: 0, maximum value: 1000, default value: 0.
# This tag requires that the tag HAVE_DOT is set to YES.
MAX_DOT_GRAPH_DEPTH = 5
MAX_DOT_GRAPH_DEPTH = 2
# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent
# background. This is disabled by default, because dot on Windows does not seem
......
doc/sphinx/ngraph_theme/footer.html
View file @ 3c830a69
......@@ -18,7 +18,7 @@
{%- if hasdoc('copyright') %}
{% trans path=pathto('copyright'), copyright=copyright|e %}&copy; <a href="{{ path }}">Copyright</a> {{ copyright }}. {% endtrans %}
{%- else %}
<span class="crt-size">{% trans copyright=copyright|e %}&copy; Copyright {{ copyright }}.</span> <br/><div class="brandnote"> Intel nGraph library contains trademarks of Intel Corporation or its subsidiaries in the U.S. and/or other countries. * Other names and brands may be claimed as the property of others; see <a href="http://ngraph.nervanasys.com/docs/latest/branding-notice.html">branding notice</a> for more information.</class>{% endtrans %}
<span class="crt-size">{% trans copyright=copyright|e %}&copy; Copyright {{ copyright }}.</span> <br/><div class="brandnote"> Intel nGraph Library contains trademarks of Intel Corporation or its subsidiaries in the U.S. and/or other countries. * Other names and brands may be claimed as the property of others; see <a href="http://ngraph.nervanasys.com/docs/latest/branding-notice.html">branding notice</a> for more information.</class>{% endtrans %}
{%- endif %}
{%- endif %}
......
doc/sphinx/ngraph_theme/static/css/theme.css
View file @ 3c830a69
......@@ -577,7 +577,7 @@ a .fa, a .rst-content .admonition-title, .rst-content a .admonition-title, a .rs
display: block;
background: #638470;
margin: -5px;
font-family: 'Faustina', sans;
font-family: 'RobotoSlab', sans;
padding: 0.43em 0.74em;
margin-bottom: 0.33em;
}
......@@ -709,7 +709,7 @@ button[disabled] {
background-color: #27AE60;
text-decoration: none;
font-weight: normal;
font-family: "NeoSansIntel", "Nanum Gothic", Arial, sans;
font-family: "NeoSansIntel", "RobotoSlab", Arial, sans;
box-shadow: 0px 1px 2px -1px rgba(255, 255, 255, 0.5) inset, 0px -2px 0px 0px rgba(0, 0, 0, 0.1) inset;
outline-none: false;
vertical-align: middle;
......@@ -1147,7 +1147,7 @@ input {
input[type="button"], input[type="reset"], input[type="submit"] {
-webkit-appearance: button;
cursor: pointer;
font-family: "NeoSansIntel", "Nanum Gothic", Arial, sans;
font-family: "NeoSansIntel", "RobotoSlab", Arial, sans;
*overflow: visible;
}
input[type="text"], input[type="password"], input[type="email"], input[type="url"], input[type="date"], input[type="month"], input[type="time"], input[type="datetime"], input[type="datetime-local"], input[type="week"], input[type="number"], input[type="search"], input[type="tel"], input[type="color"] {
......@@ -1156,7 +1156,7 @@ input[type="text"], input[type="password"], input[type="email"], input[type="url
display: inline-block;
border: 1px solid #ccc;
font-size: 80%;
font-family: "NeoSansIntel", "Nanum Gothic", Arial, sans;
font-family: "NeoSansIntel", "RobotoSlab", Arial, sans;
box-shadow: inset 0 1px 3px #ddd;
border-radius: 0;
-webkit-transition: border 0.3s linear;
......@@ -1225,7 +1225,7 @@ textarea {
overflow: auto;
vertical-align: top;
width: 100%;
font-family: "Nanum Gothic", Arial, sans;
font-family: "RobotoSlab", Arial, sans;
}
select, textarea {
......@@ -1610,17 +1610,17 @@ input[type="radio"][disabled], input[type="checkbox"][disabled] {
}
a {
color: #5c8583;
color: #a08105;
text-decoration: none;
cursor: pointer;
}
a:hover {
color: #5c8583;
background-color: #dce7e6;
color: #a08105;
text-decoration: underline;
}
a:visited {
color: #5c8583;
color: #a08105;
}
html {
......@@ -1629,9 +1629,9 @@ html {
}
body {
font-family: "Nanum Gothic", Arial, sans-serif;
font-family: "RobotoSlab", Sans, sans-serif;
font-weight: normal;
color: #404040;
color: #38403f;
min-height: 100%;
overflow-x: hidden;
background: #edf0f2;
......@@ -1709,7 +1709,7 @@ a.wy-text-neutral:hover {
h1, h2, .rst-content .toctree-wrapper p.caption, h3, h4, h5, h6, legend {
margin-top: 0.33em;
font-weight: 700;
font-family: "NeoSansIntel", "Nanum Gothic", arial, sans;
font-family: "NeoSansIntel", "RobotoSlab", arial, sans;
}
p {
......@@ -1764,8 +1764,8 @@ code, .rst-content tt, .rst-content code {
max-width: 100%;
font-size: 100%;
padding: 0 5px;
font-family: Monaco, Consolas, "Menlo", "Andale Mono WT", "Andale Mono", "Lucida Console", "Lucida Sans Typewriter", "DejaVu Sans Mono", "Bitstream Vera Sans Mono", "Liberation Mono", "Nimbus Mono L", "Courier New", Courier, monospace;
color: #E74C3C;
font-family: Inconsolata-Regular, "Lucida Console", "Lucida Sans Typewriter", "DejaVu Sans Mono", "Bitstream Vera Sans Mono", "Liberation Mono", "Nimbus Mono L", "Courier New", Courier, monospace;
color: #253237;
overflow-x: auto;
}
code.code-large, .rst-content tt.code-large {
......@@ -1816,9 +1816,8 @@ code.code-large, .rst-content tt.code-large {
list-style: disc;
}
pre, .codeblock, pre.literal-block, .rst-content .literal-block, .rst-content pre.literal-block, div[class^='highlight'] {
border: 0.05em solid #dfeef1;
padding: 0.01em;
pre, .codeblock, .rst-content .literal-block, .rst-content pre.literal-block, div[class^='highlight'] {
border: 0.079em solid #ebe9e0;
caption-side: bottom;
overflow-x: auto;
font-size: 0.97em;
......@@ -1847,7 +1846,7 @@ div[class^='highlight'] td.code {
}
code, p.caption {
font-family: Consolas, sans, monospace;
font-family: "NeoSansIntel-Light", sans, monospace;
color: #A79992;
font-size: 0.99em;
line-height: 1.39em;
......@@ -1855,7 +1854,7 @@ code, p.caption {
caption-text {
font-family: 'Nanum Gothic Coding', monospace;
font-family: 'RobotoSlab Coding', monospace;
font-family: monospace;
font-size: 1.03em;
line-height: 1.43em;
......@@ -1880,7 +1879,7 @@ div[class^='highlight'] pre {
line-height: 1.13;
display: block;
overflow: wrap;
color: #615f5e;
color: #83827d;
}
.linenodiv pre {
......@@ -2223,7 +2222,7 @@ div[class^='highlight'] pre {
color: #fcfcfc;
background: #1f1d1d;
border-top: solid 10px #5f5f5f;
font-family: "NeoSansIntel", "Nanum Gothic", "Helvetica Neue", Arial, sans;
font-family: "NeoSansIntel", "RobotoSlab", "Helvetica Neue", Arial, sans;
z-index: 400;
}
.rst-versions a {
......@@ -2435,7 +2434,7 @@ div[class^='highlight'] pre {
}
.rst-content .sidebar .sidebar-title {
display: block;
font-family: "NeoSansIntel", 'Nanum Gothic', arial, sans-serif;
font-family: "NeoSansIntel", 'RobotoSlab', arial, sans-serif;
font-weight: bold;
background: #e1e4e5;
padding: 6px 12px;
......@@ -2507,7 +2506,7 @@ div[class^='highlight'] pre {
}
.rst-content tt.literal, .rst-content tt.literal, .rst-content code.literal {
font-size: 103% !important;
color: #528481;
color: #0C7881;
line-height: 0.93em;
}
.rst-content tt.xref, a .rst-content tt, .rst-content tt.xref, .rst-content code.xref, a .rst-content tt, a .rst-content code {
......@@ -2705,13 +2704,13 @@ span[id*='MathJax-Span'] {
src: local("NeoSansIntel Bold"), local("NeoSansIntel-Bold"), url(../fonts/NeoSansIntel-Bold.ttf) format("truetype");
}
@font-face {
font-family: "Nanum Gothic";
font-family: "RobotoSlab";
font-style: normal;
font-weight: 500;
src: local("NanumGothic Regular"), local("NanumGothic-Regular"), url(../fonts/NanumGothic-Regular.ttf) format("truetype");
src: local("RobotoSlab Regular"), local("RobotoSlab-Regular"), url(../fonts/RobotoSlab-Regular.ttf) format("truetype");
}
@font-face {
font-family: "Nanum Gothic Coding";
font-family: "NanumGothic Coding";
font-style: normal;
font-weight: 700;
src: local("NanumGothicCoding Bold"), local("NanumGothicCoding-Bold"), url(../fonts/NanumGothicCoding-Bold.ttf) format("truetype");
......@@ -2765,6 +2764,7 @@ span[id*='MathJax-Span'] {
padding: 0 1.618em;
margin-bottom: 0;
display: block;
font-family: "Neo Sans Intel", sans;
font-weight: bold;
text-transform: uppercase;
font-size: 80%;
......@@ -2784,7 +2784,7 @@ span[id*='MathJax-Span'] {
background: #e3e3e3;
}
.wy-menu-vertical li.current a {
color: gray;
color: #959595;
border-right: solid 1px #c9c9c9;
padding: 0.4045em 2.427em;
}
......@@ -2904,7 +2904,7 @@ span[id*='MathJax-Span'] {
color: #e8e8e8;
}
.wy-menu-vertical a:active {
background-color: #8eb0af;
background-color: #84AEAD;
cursor: pointer;
color: #fff;
}
......@@ -2918,7 +2918,7 @@ span[id*='MathJax-Span'] {
padding: 0.809em;
margin-bottom: 0.809em;
z-index: 200;
background-color: #8eb0af;
background-color: #84AEAD;
text-align: center;
padding: 0.809em;
display: block;
......@@ -3008,9 +3008,8 @@ span[id*='MathJax-Span'] {
}
.wy-body-for-nav {
background: left repeat-y #fff;
background-image: url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAAyRpVFh0WE1MOmNvbS5hZG9iZS54bXAAAAAAADw/eHBhY2tldCBiZWdpbj0i77u/IiBpZD0iVzVNME1wQ2VoaUh6cmVTek5UY3prYzlkIj8+IDx4OnhtcG1ldGEgeG1sbnM6eD0iYWRvYmU6bnM6bWV0YS8iIHg6eG1wdGs9IkFkb2JlIFhNUCBDb3JlIDUuMy1jMDExIDY2LjE0NTY2MSwgMjAxMi8wMi8wNi0xNDo1NjoyNyAgICAgICAgIj4gPHJkZjpSREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIj4gPHJkZjpEZXNjcmlwdGlvbiByZGY6YWJvdXQ9IiIgeG1sbnM6eG1wPSJodHRwOi8vbnMuYWRvYmUuY29tL3hhcC8xLjAvIiB4bWxuczp4bXBNTT0iaHR0cDovL25zLmFkb2JlLmNvbS94YXAvMS4wL21tLyIgeG1sbnM6c3RSZWY9Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC9zVHlwZS9SZXNvdXJjZVJlZiMiIHhtcDpDcmVhdG9yVG9vbD0iQWRvYmUgUGhvdG9zaG9wIENTNiAoTWFjaW50b3NoKSIgeG1wTU06SW5zdGFuY2VJRD0ieG1wLmlpZDoxOERBMTRGRDBFMUUxMUUzODUwMkJCOThDMEVFNURFMCIgeG1wTU06RG9jdW1lbnRJRD0ieG1wLmRpZDoxOERBMTRGRTBFMUUxMUUzODUwMkJCOThDMEVFNURFMCI+IDx4bXBNTTpEZXJpdmVkRnJvbSBzdFJlZjppbnN0YW5jZUlEPSJ4bXAuaWlkOjE4REExNEZCMEUxRTExRTM4NTAyQkI5OEMwRUU1REUwIiBzdFJlZjpkb2N1bWVudElEPSJ4bXAuZGlkOjE4REExNEZDMEUxRTExRTM4NTAyQkI5OEMwRUU1REUwIi8+IDwvcmRmOkRlc2NyaXB0aW9uPiA8L3JkZjpSREY+IDwveDp4bXBtZXRhPiA8P3hwYWNrZXQgZW5kPSJyIj8+EwrlwAAAAA5JREFUeNpiMDU0BAgwAAE2AJgB9BnaAAAAAElFTkSuQmCC);
background-size: 300px 1px;
background-color: #72716f;
background-width: 300px;
}
.wy-grid-for-nav {
......@@ -3194,7 +3193,7 @@ footer span.commit code, footer span.commit .rst-content tt, .rst-content footer
}
@media screen and (min-width: 1400px) {
.wy-nav-content-wrap {
background: #fcfcfc;
background: #0C7881;
}
.wy-nav-content {
......
doc/sphinx/source/framework-integration-guides.rst
View file @ 3c830a69
......@@ -9,9 +9,15 @@ Integrate Supported Frameworks
* :ref:`neon_intg`
A framework is "supported" when there is a framework :term:`bridge` that can be
cloned from one of our GitHub repos and built to connect to a supported backend
with nGraph, all the while maintaining the framework's programmatic or user
interface. Current bridge-enabled frameworks include TensorFlow* and MXNet*.
cloned from one of our GitHub repos and built to connect to nGraph device backends,
all the while maintaining the framework's programmatic or user interface. Bridges
currently exist for the TensorFlow\* and MXNet\* frameworks.
.. figure:: graphics/bridge-to-graph-compiler.png
:width: 733px
:alt: JiT compiling of a computation
:abbr:`Just-in-Time (JiT)` Compiling for computation
Once connected via the bridge, the framework can then run and train a deep
learning model with various workloads on various backends using nGraph Compiler
......@@ -23,12 +29,12 @@ as an optimizing compiler available through the framework.
MXNet\* bridge
===============
#. See the README on `nGraph-MXNet`_ Integration for how to enable the bridge.
* See the README on `nGraph-MXNet`_ Integration for how to enable the bridge.
#. (Optional) For experimental or alternative approaches to distributed training
methodologies, including data parallel training, see the MXNet-relevant sections
of the docs on :doc:`distr/index` and :doc:`How to <howto/index>` topics like
:doc:`howto/distribute-train`.
* Optional: For experimental or alternative approaches to distributed training
methodologies, including data parallel training, see the MXNet-relevant sections
of the docs on :doc:`distr/index` and :doc:`How to <howto/index>` topics like
:doc:`howto/distribute-train`.
.. _tensorflow_intg:
......
doc/sphinx/source/frameworks/generic.rst
View file @ 3c830a69
.. frameworks/generic.rst
Working with generic frameworks
###############################
Working with other frameworks
##############################
An engineer may want to work with a deep learning framework that does not yet
have bridge code written. For non-supported or “generic” frameworks, it is
......@@ -11,7 +11,7 @@ and/or to design and document a user interface (UI) with specific runtime
options for whatever custom use case they need.
The two primary tasks that can be accomplished in the “bridge code” space of the
nGraph Abstraction layer are: (1) compiling a dataflow graph and (2) executing
nGraph abstraction layer are: (1) compiling a dataflow graph and (2) executing
a pre-compiled graph. See the :doc:`../framework-integration-guides` for how we
have built bridges with other frameworks. For more in-depth help in writing
graph optimizations and bridge code, we provide articles on how to
......@@ -20,8 +20,8 @@ target various compute resources using nGraph when a framework provides some
inputs to be computed.
Activate nGraph |trade| on generic frameworks
=============================================
Integrating nGraph with new 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
......@@ -40,9 +40,10 @@ backends.
Other, Not yet, Ask
Regardless of the framework, after the :doc:`../buildlb`, a good place to start
usually involves making the libraries available to the framework. On Linux\*
systems, that command tends to looks something like:
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:
.. code-block:: console
......
doc/sphinx/source/glossary.rst
View file @ 3c830a69
......@@ -53,6 +53,10 @@ Glossary
In the context of a function graph, a "parameter" refers to what
"stands in" for an argument in an ``op`` definition.
quantization
Quantization refers to the conversion of numerical data into a lower-precision representation. Quantization is often used in deep learning to reduce the time and energy needed to perform computations by reducing the size of data transfers and the number of steps needed to perform a computation. This improvement in speed and energy usage comes at a cost in terms of numerical accuracy, but deep learning models are often able to function well in spite of this reduced accuracy.
result
In the context of a function graph, the term "result" refers to
......@@ -104,6 +108,9 @@ Glossary
Tensors are maps from *coordinates* to scalar values, all of the
same type, called the *element type* of the tensor.
.. figure:: graphics/descriptor-of-tensor.png
:width: 559px
Tensorview
......
doc/sphinx/source/index.rst
View file @ 3c830a69
......@@ -15,55 +15,52 @@
.. This documentation is available online at
.. http://ngraph.nervanasys.com/docs/latest/
.. https://ngraph.nervanasys.com/docs/latest
########
nGraph™
########
Welcome to the nGraph™ documentation site. nGraph is an open-source C++ library
and runtime / compiler suite for :abbr:`Deep Learning (DL)` ecosystems. Our goal
is to empower algorithm designers, data scientists, framework architects,
software engineers, and others with the means to make their work :ref:`portable`,
:ref:`adaptable`, and :ref:`deployable` across the most modern
:abbr:`Machine Learning (ML)` hardware available today: optimized Deep Learning
computation devices.
Welcome
=======
.. figure:: graphics/599px-Intel-ngraph-ecosystem.png
:width: 599px
:width: 599px
.. _portable:
Portable
========
nGraph is an open-source C++ library, compiler, and runtime accelerator for
software engineering in the :abbr:`Deep Learning (DL)` ecosystem. nGraph
simplifies development and makes it possible to design, write, compile, and
deploy :abbr:`Deep Neural Network (DNN)`-based solutions. A more detailed
explanation of the feature set of nGraph Compiler, as well as a high-level
overview, can be found on our project :doc:`project/about`.
.. _quickstart:
One of nGraph's key features is **framework neutrality**. While we currently
support :doc:`three popular <framework-integration-guides>` frameworks with
pre-optimized deployment runtimes for training :abbr:`Deep Neural Network (DNN)`,
models, you are not limited to these when choosing among frontends. Architects
of any framework (even those not listed above) can use our documentation for how
to :doc:`compile and run <howto/execute>` a training model and design or tweak
a framework to bridge directly to the nGraph compiler. With a *portable* model
at the core of your :abbr:`DL (Deep Learning)` ecosystem, it's no longer
necessary to bring large datasets to the model for training; you can take your
model -- in whole, or in part -- to where the data lives and save potentially
significant or quantifiable machine resources.
Quick Start
===========
We have many documentation pages to help you get started.
* **TensorFlow or MXNet users** can get started with :doc:`framework-integration-guides`; see also:
.. _adaptable:
* `TensorFlow bridge to nGraph`_
* `Compiling MXNet with nGraph`_
Adaptable
=========
* **Data scientists** interested in the `ONNX`_ format will find the
`nGraph ONNX companion tool`_ of interest.
We've recently begun support for the `ONNX`_ format. Developers who already have
a "trained" :abbr:`DNN (Deep Neural Network)` model can use nGraph to bypass
significant framework-based complexity and :doc:`import it <howto/import>`
to test or run on targeted and efficient backends with our user-friendly
Python-based API. See the `ngraph onnx companion tool`_ to get started.
* **Framework authors and architects** will likely want to :doc:`buildlb`
and learn how nGraph can be used to :doc:`howto/execute`. For examples
of generic configurations or optimizations available when designing or
bridging a framework directly with nGraph, see :doc:`frameworks/generic`.
* To start learning about nGraph's set of **Core ops** and how they can
be used with Ops from other frameworks, go to :doc:`ops/index`.
* **Optimization pass writers** will find :doc:`fusion/index` useful. Also
look for our upcoming documentation on :term:`quantization`.
* For details about **PlaidML integration** and other nGraph runtime APIs,
see the section :doc:`programmable/index`.
.. csv-table::
:header: "Framework", "Bridge Available?", "ONNX Support?"
......@@ -73,33 +70,7 @@ Python-based API. See the `ngraph onnx companion tool`_ to get started.
MXNet, Yes, Yes
PaddlePaddle, Coming Soon, Yes
PyTorch, No, Yes
CNTK, No, Yes
Other, Custom, Custom
.. _deployable:
Deployable
==========
It's no secret that the :abbr:`DL (Deep Learning)` ecosystem is evolving
rapidly. Benchmarking comparisons can be blown steeply out of proportion by
subtle tweaks to batch or latency numbers here and there. Where traditional
GPU-based training excels, inference can lag and vice versa. Sometimes what we
care about is not "speed at training a large dataset" but rather latency
compiling a complex multi-layer algorithm locally, and then outputting back to
an edge network, where it can be analyzed by an already-trained model.
Indeed, when choosing among topologies, it is important to not lose sight of
the ultimate deployability and machine-runtime demands of your component in
the larger ecosystem. It doesn't make sense to use a heavy-duty backhoe to
plant a flower bulb. Furthermore, if you are trying to develop an entirely
new genre of modeling for a :abbr:`DNN (Deep Neural Network)` component, it
may be especially beneficial to consider ahead of time how portable and
mobile you want that model to be within the rapidly-changing ecosystem.
With nGraph, any modern CPU can be used to design, write, test, and deploy
a training or inference model. You can then adapt and update that same core
model to run on a variety of backends:
Other, Write your own, Custom
.. csv-table::
......@@ -108,25 +79,16 @@ model to run on a variety of backends:
Intel® Architecture Processors (CPUs), Yes, Yes
Intel® Nervana™ Neural Network Processor (NNPs), Yes, Yes
AMD\* GPUs, via PlaidML, Yes
NVIDIA\* GPUs, via PlaidML, Some
Intel® Architecture GPUs, Yes, Yes
AMD\* GPUs, via PlaidML, Yes
:abbr:`Field Programmable Gate Arrays (FPGA)` (FPGAs), Coming soon, Yes
NVIDIA\* GPUs, via PlaidML, Some
Intel Movidius™ Myriad™ 2 (VPU), Coming soon, Yes
Other, Not yet, Ask
The value we're offering to the developer community is empowerment: we are
confident that Intel® Architecture already provides the best computational
resources available for the breadth of ML/DL tasks. We welcome ideas and
`contributions`_ from the community.
Further project details can be found on our :doc:`project/about` page, or see
our :doc:`buildlb` guide for how to get started.
.. note:: The Library code is under active development as we're continually
adding support for more kinds of DL models and ops, framework compiler
optimizations, and backends.
adding support for more kinds of DL models and ops, compiler optimizations,
and backend optimizations.
=======
......@@ -158,8 +120,11 @@ Indices and tables
* :ref:`search`
* :ref:`genindex`
.. _nGraph ONNX companion tool: https://github.com/NervanaSystems/ngraph-onnx
.. _ONNX: http://onnx.ai
.. _ngraph onnx companion tool: https://github.com/NervanaSystems/ngraph-onnx
.. _Movidius: https://www.movidius.com/
.. _contributions: https://github.com/NervanaSystems/ngraph#how-to-contribute
\ No newline at end of file
.. _contributions: https://github.com/NervanaSystems/ngraph#how-to-contribute
.. _TensorFlow bridge to nGraph: https://github.com/NervanaSystems/ngraph-tf/blob/master/README.md
.. _Compiling MXNet with nGraph: https://github.com/NervanaSystems/ngraph-mxnet/blob/master/NGRAPH_README.md
\ No newline at end of file
doc/sphinx/source/programmable/index.rst
View file @ 3c830a69
......@@ -12,10 +12,12 @@ Backends are responsible for function execution and value allocation. They
can be used to :doc:`carry out a programmed computation<../howto/execute>`
from a framework by using a CPU or GPU; or they can be used with an *Interpreter*
mode, which is primarily intended for testing, to analyze a program, or for a
framework developer to develop a custom UI or API.
framework developer to develop customizations. Experimental APIs to support
current and future nGraph Backends are also available; see, for example, the
section on :ref:`plaidml_`.
.. figure:: ../graphics/runtime.png
.. figure:: ../graphics/backend-dgm.png
:width: 650px
......@@ -25,7 +27,6 @@ framework developer to develop a custom UI or API.
Tensor
=======
......@@ -35,3 +36,21 @@ Tensor
.. _plaidml_:
PlaidML
========
The nGraph ecosystem has recently added initial (experimental) support for `PlaidML`_,
which is an advanced :abbr:`Machine Learning (ML)` library that can further
accelerate training models built on GPUs. When you select the ``PlaidML`` option
as a backend, it behaves as an advanced tensor compiler that can further speed up
training with large data sets.
.. doxygenclass:: ngraph::runtime::plaidml::PlaidML_Backend
:project: ngraph
:members:
.. _PlaidML: https://github.com/plaidml
doc/sphinx/source/project/about.rst
View file @ 3c830a69
.. about:
Overview
========
About Features, FAQs
####################
* :ref:`features`
* :ref:`faq`
* :ref:`whats_next`
Welcome to the documentation site for |InG|, an open-source C++ Compiler,
Library, and runtime suite for Deep Learning frameworks running training and inference on
:abbr:`Deep Neural Network (DNN)` models. nGraph is framework-neutral and can be
targeted for programming and deploying :abbr:`Deep Learning (DL)` applications
on the most modern compute and edge devices.
.. _features:
Features
========
The nGraph :abbr:`Intermediate Representation (IR)` contains a combination of
device-specific and non device-specific optimization and compilations to
enable:
* **Fusion** -- Fuse multiple ``ops`` to to decrease memory usage "localities".
* **Memory management** -- Prevent peak memory usage by intercepting a graph
with or by a "saved checkpoint," and to enable data auditing.
* **Data reuse** -- Save result and reuse for subgraphs with the same input
* **Graph scheduling** -- Run similar subgraphs in parallel
* **Graph partitioning** -- Partition subgraphs to run on different devices to
speed up computation.
* :abbr:`Direct EXecution mode (DEX)` or **DEX** -- Execute kernels for the
op directly instead of using codegen when traversing the computation graph.
.. important:: See :doc:`../ops/index` to learn the nGraph means for graph
computations.
.. Our design philosophy is that the graph is not a script for running kernels;
rather, our compilation will match ``ops`` to appropriate available kernels
(or when available, such as with CPU cycles). Thus, we expect that adding of
new Core ops should be infrequent and that most functionality instead gets
added with new functions that build sub-graphs from existing core ops.
* **Data layout abstraction** -- Make abstraction easier and faster with nGraph
translating element order to work best for whatever given or available device.
.. _portable:
Portable
--------
:ref:`no-lockin`
:ref:`framework-flexibility`
One of nGraph's key features is **framework neutrality**. While we currently
support :doc:`three popular <../framework-integration-guides>` frameworks with
pre-optimized deployment runtimes for training :abbr:`Deep Neural Network (DNN)`,
models, you are not limited to these when choosing among frontends. Architects
of any framework (even those not listed above) can use our documentation for how
to :doc:`compile and run <../howto/execute>` a training model and design or tweak
a framework to bridge directly to the nGraph compiler. With a *portable* model
at the core of your :abbr:`DL (Deep Learning)` ecosystem, it's no longer necessary
to bring large datasets to the model for training; you can take your model -- in
whole, or in part -- to where the data lives and save potentially significant
or quantifiable machine resources.
.. _adaptable:
Adaptable
---------
We've recently begun support for the `ONNX`_ format. Developers who already have
a "trained" :abbr:`DNN (Deep Neural Network)` model can use nGraph to bypass
significant framework-based complexity and :doc:`import it <../howto/import>`
to test or run on targeted and efficient backends with our user-friendly
Python-based API. See the `ngraph onnx companion tool`_ to get started.
.. _deployable:
Deployable
----------
It's no secret that the :abbr:`DL (Deep Learning)` ecosystem is evolving
rapidly. Benchmarking comparisons can be blown steeply out of proportion by
subtle tweaks to batch or latency numbers here and there. Where traditional
GPU-based training excels, inference can lag and vice versa. Sometimes what we
care about is not "speed at training a large dataset" but rather latency
compiling a complex multi-layer algorithm locally, and then outputting back to
an edge network, where it can be analyzed by an already-trained model.
Indeed, when choosing among topologies, it is important to not lose sight of
the ultimate deployability and machine-runtime demands of your component in
the larger ecosystem. It doesn't make sense to use a heavy-duty backhoe to
plant a flower bulb. Furthermore, if you are trying to develop an entirely
new genre of modeling for a :abbr:`DNN (Deep Neural Network)` component, it
may be especially beneficial to consider ahead of time how portable and
mobile you want that model to be within the rapidly-changing ecosystem.
With nGraph, any modern CPU can be used to design, write, test, and deploy
a training or inference model. You can then adapt and update that same core
model to run on a variety of backends
.. _no-lockin:
Develop without lock-in
~~~~~~~~~~~~~~~~~~~~~~~
-----------------------
.. figure:: ../graphics/599px-Intel-ngraph-ecosystem.png
:width: 599px
Being able to increase training performance or reduce inference latency by
simply adding another device of *any* form factor -- more compute (CPU), GPU or
VPU processing power, custom ASIC or FPGA, or a yet-to-be invented generation of
NNP or accelerator -- is a key benefit for framework developers building with
nGraph. Our commitment to bake flexibility into our ecosystem ensures developers'
freedom to design user-facing APIs for various hardware deployments directly
into their frameworks.
.. figure:: ../graphics/develop-without-lockin.png
The value we're offering to the developer community is empowerment: we are
confident that Intel® Architecture already provides the best computational
resources available for the breadth of ML/DL tasks.
Being able to increase training performance or reduce inference latency by simply
adding another device of *any* specialized form factor -- whether it be more
compute (CPU), GPU or VPU processing power, custom ASIC or FPGA, or a yet-to-be
invented generation of NNP or accelerator -- is a key benefit for frameworks
developers working with nGraph. Our commitment to bake flexibility into our
ecosystem ensures developers' freedom to design user-facing APIs for various
hardware deployments directly into their frameworks.
.. note:: The library code is under active development as we're continually
adding support for more kinds of DL models and ops, framework compiler
optimizations, and backends.
Why was this needed?
---------------------
When Deep Learning (DL) frameworks first emerged as the vehicle for training
models, they were designed around kernels optimized for a particular platform.
As a result, many backend details were being exposed in the model definitions,
making the adaptability and portability of DL models to other, or more advanced
backends complex and expensive.
The traditional approach means that an algorithm developer cannot easily adapt
his or her model to different backends. Making a model run on a different
framework is also problematic because the user must separate the essence of
the model from the performance adjustments made for the backend, translate
to similar ops in the new framework, and finally make the necessary changes
for the preferred backend configuration on the new framework.
We designed the Intel nGraph project to substantially reduce these kinds of
engineering complexities. Our compiler-inspired approach means that developers
have fewer constraints imposed by frameworks when working with their models;
they can pick and choose only the components they need to build custom algorithms
for advanced deep learning tasks. Furthermore, if working with a model that is
already trained (or close to being trained), or if they wish to pivot and add a
new layer to an existing model, the data scientist can :doc:`../howto/import`
and start working with :doc:`../ops/index` more quickly.
.. _faq:
FAQs
=====
How does it work?
------------------
The *nGraph core* uses a **strongly-typed and platform-neutral stateless graph
representation** for computations. Each node, or *op*, in the graph corresponds
to one :term:`step` in a computation, where each step produces zero or more
tensor outputs from zero or more tensor inputs. For a more detailed dive into
how this works, read some of our :doc:`how to <../howto/execute>` articles.
The :doc:`nGraph Core <../ops/index>` uses a **strongly-typed** and
**platform-neutral** :abbr:`Intermediate Representation (IR)` to construct a
"stateless" graph. Each node, or *op*, in the graph corresponds to one
:term:`step` in a computation, where each step produces zero or more tensor
outputs from zero or more tensor inputs.
How do I connect a framework?
-----------------------------
The nGraph Library manages framework bridges for some of the more widely-known
frameworks. A bridge acts as an intermediary between the nGraph core and the
framework, and the result is a function that can be compiled from a framework.
A fully-compiled function that makes use of bridge code thus becomes a "function
graph", or what we sometimes call an **nGraph graph**.
.. note:: Low-level nGraph APIs are not accessible *dynamically* via bridge code;
this is the nature of stateless graphs. However, do note that a graph with a
"saved" checkpoint can be "continued" to run from a previously-applied
checkpoint, or it can loaded as static graph for further inspection.
.. _framework-flexibility:
For a more detailed dive into how custom bridge code can be implemented, see our
documentation on how to :doc:`../howto/execute`. To learn how TensorFlow and
MXNet currently make use of custom bridge code, see the section on
:doc:`../framework-integration-guides`.
How do I connect it to a framework?
------------------------------------
.. figure:: ../graphics/bridge-to-graph-compiler.png
:width: 733px
:alt: Compiling a computation
Currently, we offer *framework bridges* for some of the more widely-known
:doc:`frameworks <../framework-integration-guides>`. The bridge acts as an
intermediary between the *ngraph core* and the framework, providing a means
to use various execution platforms. The result is a function that can be
executed from the framework bridge.
JiT Compiling for computation
Given that we have no way to predict how many more frameworks might be invented
for either model or framework-specific purposes, it would be nearly impossible
for us to create bridges for every framework that currently exists (or that will
exist in the future). Thus, the library provides a way for developers to write
or contribute "bridge code" for various frameworks. We welcome such
contributions from the DL community.
Given that we have no way to predict how many other frameworks designed around
model, workload, or framework-specific purposes there may be, it would be
impossible for us to create bridges for every framework that currently exists
(or that will exist in the future). Although we only support a few frameworks,
we provide documentation to help developers and engineers figure out how to
get custom solutions working, such as for edge cases.
.. csv-table::
:header: "Framework", "Bridge Available?", "ONNX Support?"
:widths: 27, 10, 10
How do I connect a DL training or inference model to nGraph?
-------------------------------------------------------------
TensorFlow, Yes, Yes
MXNet, Yes, Yes
PaddlePaddle, Coming Soon, Yes
PyTorch, No, Yes
Other, Write your own, Custom
How do I run an inference model?
--------------------------------
Framework bridge code is *not* the only way to connect a model (function graph)
to nGraph's :doc:`../ops/index`. We've also built an importer for models that
......@@ -104,8 +185,10 @@ To learn how to convert such serialized files to an nGraph model, please see
the :doc:`../howto/import` documentation.
.. _whats_next:
What's next?
-------------
============
We developed nGraph to simplify the realization of optimized deep learning
performance across frameworks and hardware platforms. You can read more about
......@@ -115,5 +198,7 @@ our `arXiv paper`_ from the 2018 SysML conference.
.. _arXiv paper: https://arxiv.org/pdf/1801.08058.pdf
.. _ONNX: http://onnx.ai
.. _nGraph ONNX companion tool: https://github.com/NervanaSystems/ngraph-onnx
.. _Intel® MKL-DNN: https://github.com/intel/mkl-dnn
.. _Movidius: https://developer.movidius.com/
doc/sphinx/source/project/index.rst
View file @ 3c830a69
......@@ -6,7 +6,6 @@ More about nGraph
This section contains documentation about the project and how to contribute.
.. toctree::
:maxdepth: 1
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment