Skip to content

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

Fix project README to be current, new doxyfile config test, cleanup s… (#433) 

* Fix project README to be current, new doxyfile config test, cleanup static dir of theme

* make sure new README gets added

* fixes on doc cleanup branch

* Add feedback from github reviews

* Fix core README again
parent c3364269
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 83 additions and 212 deletions
README.md
View file @ 5997654e
# Overview
TODO
# Intel® nGraph™ library project
# Building `libngraph`
Welcome to the Intel nGraph project, an open source C++ library for developers
of Deep Learning (DL) systems. Here you will find a suite of components, APIs,
and documentation that can be used to compile and run Deep Neural Network (DNN)
models defined in a variety of frameworks.
## Build Environments
The nGraph library translates a framework’s representation of computations into
an Intermediate Representation (IR) designed to promote computational efficiency
on target hardware. Initially-supported backends include Intel Architecture CPUs,
the Intel® Nervana Neural Network Processor™ (NNP), and NVIDIA\* GPUs.
Currently-supported compiler optimizations include efficient memory management
and data layout abstraction.
| Operating System | Compiler | Build system | Status | Additional packages required |
| --------------------------- | --------- | ---------------------- | ---------------------- | --------------------------------- |
| Ubuntu 16.04 (LTS) 64-bit | CLang 3.9 | CMake 3.5.1 + GNU Make | supported | `build-essential cmake clang-3.9` |
| Ubuntu 16.04 (LTS) 64-bit | CLang 4.0 | CMake 3.5.1 + GNU Make | unsupported, but works | `build-essential cmake clang-4.0` |
See our [install] docs for how to get started.
## Steps
_If you are developing ngraph on macOS (officially unsupported) please see the section "macOS Development Prerequisites" below._
`libngraph` is build in the customary manner for a CMake-based project:
1. Create a build directory outside of source directory tree.
2. `cd` to the build directory.
3. Run `cmake`. For example, `cmake ../`
4. Run `make -j8`.
5. Run `make install`.
* This will install `libngraph.so` and the header files to `$HOME/ngraph_dist`.
6. _(Optional, requires `doxygen`)_ Run `make doc`.
* This will build API documentation in the directory `doc` inside the build directory.
## macOS Development Prerequisites
The repository includes two scripts (`maint/check-code-format.sh` and `maint/apply-code-format.sh`) that are used respectively to check adherence to `libngraph` code formatting conventions, and to automatically reformat code according to those conventions. These scripts require the command `clang-format-3.9` to be in your `PATH`. Run the following commands (you will need to adjust them if you are not using `bash`).
```
$ brew install llvm@3.9
$ mkdir -p $HOME/bin
$ ln -s /usr/local/opt/llvm@3.9/bin/clang-format $HOME/bin/clang-format-3.9
$ echo 'export PATH=$HOME/bin:$PATH' >> $HOME/.bash_profile
```
# Testing `libngraph`
`libngraph` uses the GTest framework for unit tests. CMake automatically downloads a
copy of the required GTest files when configuring the build directory.
To perform the unit tests
1. Configure the build directory as described above.
2. Change directory to the build directory.
3. Run `make check`
# Using `libngraph`
## From Tensorflow as XLA plugin
:warning: Note: Work in Progress.
1. Get the Nervana's fork of the TF from this repo: ```git@github.com:NervanaSystems/ngraph-tensorflow.git```
2. Go to the end near the following snippet:
```
native.new_local_repository(
name = "ngraph_external",
path = "/your/home/directory/where/ngraph_is_installed",
build_file = str(Label("//tensorflow/compiler/plugin/ngraph:ngraph.BUILD")),
)
```
Then modify the following line in `tensorflow/workspace.bzl` file and provide absolute path to `~/ngraph_dist` :
```
path = "/your/home/directory/where/ngraph_is_installed",
```
3. Now run `configure` and rest of the TF build.
## System Requirements
TBD
## External library requirements
TBD
# Maintaining `libngraph`
## Code formatting
All C/C++ source code in the `libngraph` repository, including the test code when practical,
should adhere to the project's source-code formatting guidelines.
The script `maint/apply-code-format.sh` enforces that formatting at the C/C++ syntactic level.
The script `maint/check-code-format.sh` verifies that the formatting rules are met by all C/C++
code (again, at the syntax level.) The script has an exit code of 0 when this all code meets
the standard, and non-zero otherwise. This script does _not_ modify the source code.
For this early release, we provide framework integration guides to compile
MXNet and TensorFlow-based projects.
[install]: doc/sphinx/source/installation.rst
doc/sphinx/ngraph.doxyfile
View file @ 5997654e
This diff is collapsed.
doc/sphinx/ngraph_theme/static/css/theme.css
View file @ 5997654e
......@@ -361,7 +361,7 @@ big, small {
display: inline-block;
font: normal normal normal 1.011em/1 NeoSansIntel;
font-size: inherit;
letter-spacing: -0.41em;
letter-spacing: -0.05em;
text-rendering: auto;
-webkit-font-smoothing: antialiased;
-moz-osx-font-smoothing: grayscale;
......@@ -495,14 +495,6 @@ big, small {
transform: scale(1, -1);
}
:root .fa-rotate-90,
:root .fa-rotate-180,
:root .fa-rotate-270,
:root .fa-flip-horizontal,
:root .fa-flip-vertical {
filter: none;
}
.fa-stack {
position: relative;
display: inline-block;
......@@ -585,8 +577,10 @@ a .fa, a .rst-content .admonition-title, .rst-content a .admonition-title, a .rs
color: #fff;
background: #6ab0de;
margin: -12px;
padding: 6px 12px;
margin-bottom: 12px;
font-family: 'NeoSansIntel', sans;
letter-spacing: 0.05em;
padding: 0.33em 0.74em;
margin-bottom: 0.33em;
}
.wy-alert.wy-alert-danger, .rst-content .wy-alert-danger.note, .rst-content .wy-alert-danger.attention, .rst-content .wy-alert-danger.caution, .rst-content .danger, .rst-content .error, .rst-content .wy-alert-danger.hint, .rst-content .wy-alert-danger.important, .rst-content .wy-alert-danger.tip, .rst-content .wy-alert-danger.warning, .rst-content .wy-alert-danger.seealso, .rst-content .wy-alert-danger.admonition-todo {
......@@ -1716,7 +1710,7 @@ a.wy-text-neutral:hover {
h1, h2, .rst-content .toctree-wrapper p.caption, h3, h4, h5, h6, legend {
margin-top: 0;
font-weight: 700;
font-family: "NeoSansIntel", "Roboto Slab", "ff-tisa-web-pro", "Georgia", Arial, sans-serif;
font-family: "NeoSansIntel", "RobotoSlab", "ff-tisa-web-pro", "Georgia", Arial, sans;
}
p {
......@@ -1731,15 +1725,18 @@ h1 {
}
h2, .rst-content .toctree-wrapper p.caption {
font-size: 141%;
font-size: 139%;
}
h3 {
font-size: 127%;
font-weight: lighter;
}
h4 {
font-size: 100%;
font-weight: lighter;
}
h5 {
......
doc/sphinx/ngraph_theme/static/css/theme.css.backup
View file @ 5997654e
......@@ -361,7 +361,7 @@ big, small {
display: inline-block;
font: normal normal normal 1.011em/1 NeoSansIntel;
font-size: inherit;
letter-spacing: -0.41em;
letter-spacing: -0.05em;
text-rendering: auto;
-webkit-font-smoothing: antialiased;
-moz-osx-font-smoothing: grayscale;
......@@ -495,14 +495,6 @@ big, small {
transform: scale(1, -1);
}
:root .fa-rotate-90,
:root .fa-rotate-180,
:root .fa-rotate-270,
:root .fa-flip-horizontal,
:root .fa-flip-vertical {
filter: none;
}
.fa-stack {
position: relative;
display: inline-block;
......@@ -585,8 +577,10 @@ a .fa, a .rst-content .admonition-title, .rst-content a .admonition-title, a .rs
color: #fff;
background: #6ab0de;
margin: -12px;
padding: 6px 12px;
margin-bottom: 12px;
font-family: 'NeoSansIntel', sans;
letter-spacing: 0.05em;
padding: 0.33em 0.74em;
margin-bottom: 0.33em;
}
.wy-alert.wy-alert-danger, .rst-content .wy-alert-danger.note, .rst-content .wy-alert-danger.attention, .rst-content .wy-alert-danger.caution, .rst-content .danger, .rst-content .error, .rst-content .wy-alert-danger.hint, .rst-content .wy-alert-danger.important, .rst-content .wy-alert-danger.tip, .rst-content .wy-alert-danger.warning, .rst-content .wy-alert-danger.seealso, .rst-content .wy-alert-danger.admonition-todo {
......@@ -1716,7 +1710,7 @@ a.wy-text-neutral:hover {
h1, h2, .rst-content .toctree-wrapper p.caption, h3, h4, h5, h6, legend {
margin-top: 0;
font-weight: 700;
font-family: "NeoSansIntel", "Roboto Slab", "ff-tisa-web-pro", "Georgia", Arial, sans-serif;
font-family: "NeoSansIntel", "RobotoSlab", "ff-tisa-web-pro", "Georgia", Arial, sans;
}
p {
......@@ -1731,15 +1725,18 @@ h1 {
}
h2, .rst-content .toctree-wrapper p.caption {
font-size: 141%;
font-size: 139%;
}
h3 {
font-size: 127%;
font-weight: lighter;
}
h4 {
font-size: 100%;
font-weight: lighter;
}
h5 {
......
doc/sphinx/ngraph_theme/static/fonts/PKGBUILD deleted 100644 → 0
View file @ c3364269
# Maintainer: Gavin Lloyd
# https://github.intel.com/gavinllo/ttf-neo-sans-intel
pkgname=ttf-neo-sans-intel
pkgver=1.00
pkgrel=3
pkgdesc='Versatile, futuristic typeface for Intel-branded material'
arch=('ANY')
depends=('fontconfig' 'xorg-font-utils')
source=('NeoSansIntel-Italic.ttf'
'NeoSansIntel-LightItalic.ttf'
'NeoSansIntel-Light.ttf'
'NeoSansIntel-MediumItalic.ttf'
'NeoSansIntel-Medium.ttf'
'NeoSansIntel.ttf')
sha256sums=('be2f036d58320bd0fab7cca7327b806840ddfedfdc4e44a520a85bd53a1ed7b3'
'ce45deb38ad2749ba25cbb76084955e34a86f627043f1f0f8f8073720115545c'
'd522c9c3905532680f8bb8068fa340200d2e5e45376ea89d97bcc8edbce8eff8'
'61b3ce0ed96b6f343c8ac0a94471ed504708782bee7d9df88fadc564640ffbba'
'6cd878034142c390eeb98d2a17ee1b949c2f8ded0a8684d3b17e0fe4203a8fd8'
'303bc44874e23a563775e5d463a6ec3dd7bdfc7948fa95d65a45fa965bf5ee28')
package() {
install -d $pkgdir/usr/share/fonts/TTF/
install -m644 *.ttf $pkgdir/usr/share/fonts/TTF/
}
doc/sphinx/source/about.rst
View file @ 5997654e
......@@ -4,14 +4,16 @@ About
=====
Welcome to the Intel nGraph project, an open source C++ library for developers
of :abbr:`Deep Learning (DL)` (DL) systems and frameworks. Here you will find
a suite of components, documentation, and APIs that can be used with
of :abbr:`Deep Learning (DL)` (DL) systems. Here you will find a suite of
components, APIs, and documentation that can be used to compile and run
:abbr:`Deep Neural Network (DNN)` models defined in a variety of frameworks.
The nGraph library translates a framework’s representation of computations into
a neutral-:abbr:`Intermediate Representation (IR)` designed to promote
computational efficiency on target hardware; it works on Intel and non-Intel
platforms.
an :abbr:`Intermediate Representation (IR)` designed to promote computational
efficiency on target hardware. Initially-supported backends include Intel
Architecture CPUs, the Intel® Nervana Neural Network Processor™ (NNP),
and NVIDIA\* GPUs. Currently-supported compiler optimizations include efficient
memory management and data layout abstraction.
.. figure:: graphics/fig.jpeg
......@@ -22,32 +24,19 @@ outputs from zero or more tensor inputs.
There is a *framework bridge* for each supported framework which acts as
an intermediary between the *ngraph core* and the framework. A *transformer*
plays a similar role between the ngraphcore and the various execution
plays a similar role between the ngraph core and the various execution
platforms.
Transformers compile the graph using a combination of generic and
platform-specific graph transformations. The result is a function that
can be executed from the framework bridge. Transformers also allocate
and deallocate, as well as read and write, tensors under direction of the
and deallocate, as well as read and write tensors under direction of the
bridge.
For this early |release| release, we provide framework integration guides
to
* :ref:`mxnet_intg`,
* :ref:`tensorflow_intg`, and
* Try neon™ `frontend`_ framework for training GPU-performant models.
Integration guides for each of these other frameworks is tentatively
forthcoming and/or open to the community for contributions and sample
documentation:
* `Chainer`_,
* `PyTorch`_,
* `Caffe2`_, and
* Frameworks not yet written (for algorithms that do not yet exist).
.. _Caffe2: https://github.com/caffe2/
.. _PyTorch: http://pytorch.org/
.. _Chainer: https://chainer.org/
We developed Intel nGraph to simplify the realization of optimized deep
learning performance across frameworks and hardware platforms. You can
read more about design decisions and what is tentatively in the pipeline
for development in our `SysML conference paper`_.
.. _frontend: http://neon.nervanasys.com/index.html/
.. _SysML conference paper: https://arxiv.org/pdf/1801.08058.pdf
\ No newline at end of file
doc/sphinx/source/conf.py
View file @ 5997654e
......@@ -191,15 +191,8 @@ texinfo_documents = [
html_add_permalinks = ""
breathe_projects = {
"nGraph": "../../../build/doc/doxygen/xml",
"nGraph": "../../../doxygen/xml",
}
breathe_default_project = "nGraph"
breathe_projects = {
"nGraph": "xml"
}
rst_epilog = u"""
.. |codename| replace:: Intel nGraph
......
doc/sphinx/source/index.rst
View file @ 5997654e
......@@ -18,16 +18,21 @@ Intel nGraph library project
#############################
Welcome to the Intel nGraph project, an open source C++ library for developers
of :abbr:`Deep Learning (DL)` (DL) systems and frameworks. Here you will find
a suite of components, documentation, and APIs that can be used with
:abbr:`Deep Neural Network (DNN)` models defined in a variety of frameworks.
of :abbr:`Deep Learning (DL)` (DL) systems. Here you will find a suite of
components, APIs, and documentation that can be used to compile and run
:abbr:`Deep Neural Network (DNN)` (DNN) models defined in a variety of frameworks.
For this early release, we provide :doc:`framework-integration-guides` to compile
and run MXNet and TensorFlow-based projects.
The nGraph library translates a framework’s representation of computations into
a neutral-:abbr:`Intermediate Representation (IR)` designed to promote
computational efficiency on target hardware; it works on Intel and non-Intel
platforms.
an :abbr:`Intermediate Representation (IR)` designed to promote computational
efficiency on target hardware. Initially-supported backends include Intel
Architecture CPUs (CPU), the Intel® Nervana Neural Network Processor™ (NNP),
and NVIDIA\* GPUs. Currently-supported compiler optimizations include efficient
memory management and data layout abstraction.
For further overview details, see the :doc:`about` page.
Further overview details can be found on our :doc:`about` page.
=======
......@@ -46,10 +51,6 @@ For further overview details, see the :doc:`about` page.
:caption: Algorithms
:name:
.. toctree::
:maxdepth: 2
:caption: Backend Components
.. toctree::
:maxdepth: 1
:caption: Reference API
......@@ -80,9 +81,9 @@ For further overview details, see the :doc:`about` page.
doc-contributor-README.rst
Indices and tables
==================
* :ref:`search`
* :ref:`genindex`
\ No newline at end of file
* :ref:`genindex`
\ No newline at end of file
doc/sphinx/source/installation.rst
View file @ 5997654e
......@@ -8,8 +8,8 @@ Build Environments
==================
The |release| version of |project| supports Linux\* or UNIX-based
systems where the system has been recently updated with the following
packages and prerequisites:
systems which have recent updates of the following packages and
prerequisites:
.. csv-table::
:header: "Operating System", "Compiler", "Build System", "Status", "Additional Packages"
......@@ -21,8 +21,8 @@ packages and prerequisites:
Ubuntu 16.04 (LTS) 64-bit, CLang 4.0, CMake 3.5.1 + GNU Make, officially unsupported, ``build-essential cmake clang-4.0 git libtinfo-dev``
Clear Linux\* OS for Intel Architecture, CLang 5.0.1, CMake 3.10.2, experimental, bundles ``machine-learning-basic dev-utils python3-basic python-basic-dev``
macOS support is limited; see the macOS development prerequisites section
at the end of this page for details.
Support for macOS is limited; see the macOS development prerequisites
section at the end of this page for details.
Installation Steps
......@@ -37,7 +37,7 @@ information about how to change or customize this location.
framework will take place locally through Pythonic APIs to the C++
library, you can set a reference placeholder for the documented source
cloned from the repo. Create something like ``/opt/local`` and (with sudo
permissions), give ownership of that local directory to your user.
permissions), give ownership of that directory to your user.
.. code-block:: console
......@@ -55,7 +55,7 @@ information about how to change or customize this location.
$ cd private-ngraph-cpp
#. Create a build directory outside of the ``private-ngraph-cpp/src`` directory
tree; something like ``private-ngraph-cpp/build`` should work.
tree; somewhere like ``private-ngraph-cpp/build``, for example.
.. code-block:: console
......@@ -79,8 +79,9 @@ information about how to change or customize this location.
#. (Optional, requires `Sphinx`_.) Run ``make html`` inside the
``doc/sphinx`` directory to build HTML docs for the nGraph library.
#. (COMING SOON -- Generate API docs. Optional, requires `doxygen`_.) TBD
#. (Optional, requires `doxygen`_.) Run ``$ make htmldocs`` inside
the ``doc/sphinx`` directory to build HTML API docs inside the
``/docs/doxygen/`` directory.
macOS Development Prerequisites
......
doc/sphinx/source/release-notes.rst
View file @ 5997654e
......@@ -3,4 +3,5 @@
Release Notes
#############
This is the |release| release.
doc/sphinx/source/testing-libngraph.rst
View file @ 5997654e
.. testing-libngraph:
##########################
Testing the nGraph library
##########################
########################
Test the nGraph library
########################
The |InG| library code base uses the `GTest framework`_ for unit tests. CMake
automatically downloads a copy of the required GTest files when configuring the
......@@ -29,27 +28,16 @@ After building and installing the nGraph library to your system, the next
logical step is to compile a framework that you can use to run a
training/inference model with one of the backends that are now enabled.
For this early release, we provide integration guides for
For this early |release| release, we're providing integration guides for:
* `MXNet`_,
* `TensorFlow`_, and
* neon™ `frontend framework`_
Integration guides for each of these other frameworks is tentatively
forthcoming and/or open to the community for contributions and sample
documentation:
* neon™ `frontend framework`_.
* `Chainer`_,
* `PyTorch`_,
* `Caffe2`_, and
* Frameworks not yet written (for algorithms that do not yet exist).
Integration guides for other frameworks is tentatively forthcoming.
.. _GTest framework: https://github.com/google/googletest.git
.. _MXNet: http://mxnet.incubator.apache.org/
.. _TensorFlow: https://www.tensorflow.org/
.. _Caffe2: https://github.com/caffe2/
.. _PyTorch: http://pytorch.org/
.. _Chainer: https://chainer.org/
.. _frontend framework: http://neon.nervanasys.com/index.html/
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